コンテンツにスキップ

取得



GET /api/v1/account/get

概要

アカウントUUIDまたはサードパーティアカウントIDでアカウント情報を取得します。

呼び出し前の準備と使用手順

r または w 権限の External 認証情報を使用します。accountUUIDはアカウント一覧のuuidから取得し、exterIdはお客様のIDシステムから取得します。両方のうち少なくとも1つを指定する必要があり、両方を指定した場合は積集合を取得します。無効化済みアカウントはエラーになります。無効化済みアカウントの情報を照会する場合は一覧を使用してください。ワークスペースロールが必要な場合は、有効なaccountUUIDとwsRoleNeeded=trueを同時に指定します。exterIdのみの場合は、現在の実装ではwsInfo=[]が返されます。

リクエストヘッダー

パラメータ名 型 必須 説明
X-Df-SVersion string 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを継続使用することはできません。
例: v20240417
取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。
X-Df-Access-Key string Y 読み取りインターフェースではrまたはwの認証情報を使用でき、書き込みインターフェースではwの認証情報が必要です。
例: <external-access-key>
取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。
X-Df-Nonce string Y 一時的なシリアル番号。失敗して再送する場合も新しい値を生成し、署名を再計算します。
例: 97d275ee9f774315a7885ba7347acbd9
取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。
X-Df-Signature string Y 大文字のメソッド、nonce、元の完全なパス、timestamp、および元のUTF-8リクエストボディをスペースで連結し、HMAC-SHA256を計算してhexダイジェストを取得します。
例: <hmac-sha256-hex>
取得または入力方法: External API 署名認証に従って対応するSKで計算します。完全に実行可能なテンプレートは以下を参照してください。
X-Df-Timestamp string Y サイトで設定された署名の有効時間枠内である必要があり、例の時刻を再利用することはできません。
例: 1785427200
取得または入力方法: 送信時に str(int(time.time())) で現在のUnix秒文字列を生成します。

Query リクエストパラメータ

パラメータ名 型 必須 説明
accountUUID string アカウントUUID。exterIdと同時に指定できます。省略した場合はexterIdで照会します。
null 許可: False
例: acnt_example001
取得または入力方法: アカウント一覧のcontent.data[].uuid、または作成成功レスポンスのcontent.uuidから取得します。
exterId string サードパーティID。accountUUIDと同時に指定できます。両方指定する場合は同一のアカウントを指す必要があります。
null 許可: False
例: sso-user-1001
取得または入力方法: このサードパーティアカウント作成時に渡した一意の識別子を使用します。
wsRoleNeeded string 文字列trueまたは1で有効、それ以外の文字列では無効となり、デフォルトではwsInfoを返しません。
null 許可: False
例: true
取得または入力方法: ワークスペースとロールを直接取得する場合は文字列trueまたは1を指定します。不要な場合は省略するかfalseを指定します。

パラメータ補足説明

サイトレベルのExternal API認証情報を使用します。認証方式はExternal API 署名認証を参照してください。以下の例ではv20240417署名バージョンを使用し、署名パス、Queryエンコード、および元のリクエストボディは実際に送信する内容と完全に一致させる必要があります。返されるアカウント情報にはpasswordフィールドは含まれません。mfaSecretは固定のマスクのみで、ログインに使用できるキーではありません。

リクエスト例

import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen

# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えてください。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/account/get'
query = {'accountUUID': 'acnt_example001', 'wsRoleNeeded': 'true'}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
    "X-Df-Access-Key": access_key,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-Signature": signature,
    "X-Df-SVersion": "v20240417",
}
if data is not None:
    headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
    print(result.read().decode("utf-8"))

レスポンス

HTTP 200、Content-Typeはapplication/json、統一レスポンスエンベロープです。業務データはcontentにあります。External APIはdeclarationを自動的に追加せず、一覧のページネーションはcontent.pageInfoに保持されます。

フィールド 型 説明
content.id integer サイト内のアカウントレコード連番。情報の返却のみに使用し、他のインターフェースの呼び出しにはuuidを使用します。
content.uuid string アカウントUUID。以降の照会、変更、無効化、削除ではこのフィールドを使用します。
content.status integer アカウントステータス: 0は正常、2は無効。一覧では3(削除済み)をフィルタしますが、その他の履歴ステータスが現れる場合があります。
content.creator string 作成者の識別子。Externalで作成した場合は通常SYSです。
content.updator string 最終更新者の識別子。まだ更新がない場合は空になることがあります。
content.createAt number 作成時刻(Unix秒)。
content.updateAt number 更新時刻(Unix秒)。まだ更新時刻がない場合は-1になることがあります。
content.deleteAt number ステータス操作時刻のフィールド。初期値は通常-1です。有効化/無効化でもこの値が書き込まれるため、削除の判断をこの値のみに依存せず、statusを使用してください。
content.name string 表示ニックネーム。
content.username string ログインアカウント名。サードパーティアカウントでは空の場合や、他のアカウントと重複する場合があります。
content.email string アカウントの連絡先メールアドレス。作成時に空で、usernameがメール形式の場合はusernameで補完されます。
content.mobile string 携帯電話番号のローカル番号。復号して表示され、国コードは含みません。未設定の場合は空文字列です。
content.countryCode string 携帯電話番号の国/地域コード(数字のみの文字列、例: 86)。未設定の場合は空文字列です。
content.exterId string サードパーティIDシステムの一意ID。ローカルアカウントでは通常空です。
content.extend object または null 既存の拡張情報。user_icon(アバターアドレス)を含む場合があります。本インターフェースの作成時に渡したextendは現在保存されず、変更インターフェースでもこの入力パラメータは公開されていません。
content.extend.user_icon string 任意のアバターURLまたは静的リソースのファイル名。履歴情報の読み取り時に現れる場合があり、本ページで書き込み可能なパラメータではありません。
content.source string アイデンティティソースの識別子。例: local、unknown、oidc、ldap。agentなど過去の内部ソースが存在する場合もあります。
content.nameSpace string アイデンティティの名前空間。Externalで作成した場合はデフォルトで空です。本モジュールの公開パラメータでは設定できません。
content.isUsed integer または boolean アカウントが使用済みかどうかのフラグ。
content.agreeTerms integer 規約同意フラグ。
content.canaryPublic boolean カナリアフラグ。
content.enableMFA boolean MFAを有効にするかどうか。
content.mfaSecret string 固定のマスク*********************で、使用可能なMFAキーは含まれません。
content.language string 言語識別子。zh、en、zh-hant、id、ja、ko。
content.tokenHoldTime integer アカウントの無操作セッション保持時間(秒)。新規アカウントはサイトのセキュリティセッション設定に従って初期化されるため、例の値に固定されるとは限りません。
content.tokenMaxValidDuration integer アカウントセッションの最大有効期間(秒)。新規アカウントはサイトのセキュリティセッション設定に従って初期化されます。
content.timezone string タイムゾーン識別子。未設定の場合は空です。
content.attributes object SSO同期属性のKVオブジェクト。以降のSSOログインで上書きされる場合があります。キーと値は連携先が取り決めます。
content.attributes.{属性名} 任意のJSON値 カスタム属性値。文字列の使用を推奨します。例: 部门=研发部
content.customAttributes object 業務側で保守する属性のKVオブジェクト。
content.customAttributes.{属性名} 任意のJSON値 業務カスタム値。文字列の使用を推奨します。例: costCenter=CC-1001
content.statusPageSubs integer ステータスページ購読フラグ。
content.defaultWorkspace string アカウントのデフォルトワークスペースUUID。未設定の場合は空です。
content.brandKey string アカウントの現在のブランド識別子。サイトで許可されたブランド集合によって決まります。
content.scheduleMobile string シフト専用携帯電話番号のローカル番号。未設定の場合は空です。
content.scheduleEmail string シフト専用メールアドレス。未設定の場合は空です。
content.ifScheduleMobileEnable boolean シフト用携帯電話番号を有効にするかどうか。
content.ifScheduleEmailEnable boolean シフト用メールアドレスを有効にするかどうか。
content.accountStatus string アカウントの付加ステータス識別子。未設定の場合は空です。
content.userIconUrl string または null 既存のextend.user_iconに基づいて生成されたアバターURL。アバターがない場合はnullです。
content.wsInfo オブジェクト配列または null アカウントに直接バインドされた有効なワークスペースおよびロール。管理バックエンドのグループからのみ継承された権限は含みません。
content.wsInfo[].uuid string ワークスペースUUID。
content.wsInfo[].name string ワークスペース名。
content.wsInfo[].roles オブジェクト配列 このアカウントに直接関連付けられた有効なロール。
content.wsInfo[].roles[].uuid string ロールUUID。例: owner。
content.wsInfo[].roles[].name string ロールの表示名。
content.wsInfo[].roles[].workspaceUUID string ロール定義が属するワークスペースUUID。システム共通ロールの場合は空文字列です。
{
  "code": 200,
  "content": {
    "id": 1001,
    "uuid": "acnt_example001",
    "status": 0,
    "creator": "SYS",
    "updator": "",
    "createAt": 1785427200,
    "deleteAt": -1,
    "updateAt": -1,
    "name": "示例成员",
    "username": "xxx@guance.com",
    "email": "xxx@guance.com",
    "mobile": "",
    "countryCode": "",
    "exterId": "",
    "extend": null,
    "source": "local",
    "nameSpace": "",
    "isUsed": 0,
    "agreeTerms": 0,
    "canaryPublic": false,
    "enableMFA": false,
    "mfaSecret": "*********************",
    "language": "zh",
    "tokenHoldTime": 86400,
    "tokenMaxValidDuration": 604800,
    "timezone": "",
    "attributes": {
      "部门": "研发部"
    },
    "customAttributes": {
      "costCenter": "CC-1001"
    },
    "statusPageSubs": 0,
    "defaultWorkspace": "",
    "brandKey": "guance",
    "scheduleMobile": "",
    "scheduleEmail": "",
    "ifScheduleMobileEnable": false,
    "ifScheduleEmailEnable": false,
    "accountStatus": "",
    "userIconUrl": null,
    "wsInfo": [
      {
        "uuid": "wksp_example001",
        "name": "示例空间",
        "roles": [
          {
            "uuid": "general",
            "name": "普通成员",
            "workspaceUUID": ""
          }
        ]
      }
    ]
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。

HTTP ステータス errorCode 発生条件 メッセージまたは応答の説明 対応方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
404 ft.NotFoundAccount 照会条件を満たすアカウントが見つからない、またはアカウントがすでに削除されている 指定されたアカウントが見つかりません アカウント一覧から有効なuuidを再取得してください。2つの条件で照会する場合は、両方の値が同一アカウントに属するか確認してください。
403 ft.AccountIsDisabled 対象アカウントのstatus=2 アカウントが無効化されています まず有効化/無効化インターフェースで有効化するか、一覧でアカウントステータスを確認してください。
500 ft.InternalServerError データベース、キャッシュ、非同期タスクの投入、または明示的に処理されていないフィールドの異常 内部エラー traceIdを保存して管理者に連絡してください。書き込みリクエストの場合は、まずアカウントの現状を再照会し、確認したうえで再試行するか判断してください。500をそのまま「未適用」と見なすことはできません。

フィードバック

このページは役に立ちましたか?