取得¶
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をそのまま「未適用」と見なすことはできません。 |