取得¶
GET /api/v1/workspace/accesskey/{ak_uuid}/get
概要¶
API Key レコードの UUID に基づいて、認証情報、バインドされたアイデンティティ、および現在有効な権限を読み取ります。
呼び出し前の準備と使用手順¶
この API は GET ですが、仕様上は w 権限の External 認証情報が必要です。UUID は API Key リスト または作成レスポンスから取得します。追加の workspaceUUID による制限はないため、まず返却された content.workspaceUUID を確認してください。手動 Key と、UUID が既知の非システムのアカウントバインド Key はどちらも照会できます。手動 Key の権限はそのロール関係に従い、有効なロール関係がない場合は管理者にフォールバックできます。アカウントバインド Key の権限は、アカウントのワークスペースロールに応じて変化します。返却される roles/permissions/rolePermissions が有効な権限の要約です。作成時または変更時の roleInfo が空配列であることだけから権限なしと推測しないでください。読み取りによって Key が消費または破棄されることはありません。
パスパラメーター¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| ak_uuid | string | Y | API Key レコード UUID(通常 wsak_ プレフィックス)。ak/sk 呼び出し認証情報ではありません。この External パスは UUID によりワークスペースを横断して特定するため、実行前に workspaceUUID を確認してください。 例: wsak_example001取得または入力方法: API Key リスト の content.data[].uuid、または作成成功時の content.uuid から取得します。 |
リクエストヘッダー¶
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したうえで本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 本モジュールのリストでは r または w 権限を使用できます。その他の API(GET 詳細を含む)には w 権限の External 認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: 各リクエストで uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字の HTTP メソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を実行して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従って対応する SK で計算します。完全に実行可能なテンプレートは下記を参照してください。 |
| X-Df-Timestamp | string | Y | サイト設定の署名有効時間枠内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) で現在の Unix 秒文字列を生成します。 |
パラメーター補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式は External API 署名認証 を参照してください。本ページで生成されるワークスペース API Key と External 署名認証情報は同じ認証情報セットではありません。External は現在 AK/SK を平文で返すため、フロントエンド画面のマスクポリシーを適用しないでください。レスポンス例はすべてプレースホルダー値を使用しているため、実際のレスポンスは認証情報として保管してください。
リクエスト例¶
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/workspace/accesskey/wsak_example001/get'
query = {}
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。application/json の共通エンベロープを使用し、業務結果は content にあります。External は declaration を自動的に追加しません。リストのページネーションは content.pageInfo にあります。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | 内部レコード番号。API 呼び出しでは uuid を使用します。作成スナップショットは flush 前に取得されるため、このフィールドは null になる場合があります。 |
| content.uuid | string | API Key レコード UUID。呼び出し認証情報の ak/sk とは異なります。 |
| content.status | integer | Key の状態: 0 有効、2 無効、3 削除済み。リスト/詳細では 0 のみ返されます。削除操作は、未削除の無効化済み Key も処理できます。 |
| content.creator | string | 作成アイデンティティ。External による作成では通常 external です。 |
| content.updator | string | 更新アイデンティティ。未変更の場合は空になることがあります。 |
| content.createAt | integer | 作成 Unix 秒。 |
| content.deleteAt | integer | 削除 Unix 秒。未削除の場合は通常 -1 です。 |
| content.updateAt | integer | 更新 Unix 秒。まだ変更されていない場合は通常 -1 です。 |
| content.name | string | API Key の表示名。 |
| content.ak | string | ワークスペース Access Key 呼び出し認証情報の平文。このワークスペースの OpenAPI 認証に使用でき、本 External リクエストの X-Df-Access-Key ではありません。 |
| content.sk | string | ワークスペース Secret Key の平文。機密認証情報として保存してください。この External リクエストに対応する SK ではありません。 |
| content.workspaceUUID | string | 所属ワークスペースの UUID。 |
| content.accountUUID | string | バインドされたアカウントの UUID。手動のワークスペース Key では空文字列です。アカウントバインド Key の有効権限はアカウントロールに基づいて確認する必要があります。 |
| content.createdWay | string | 生成元識別子(例: manual、user、agent)。リストでは accountUUID が空でないすべての Key が除外されます。 |
| content.businessType | string | システム業務タイプ識別子。手動 Key では通常空です。 |
| content.isSystem | integer | システム組み込み Key かどうか。本モジュールの照会/操作ではシステム Key がフィルタリングされます。 |
| content.isOwnerRole | integer | Owner 専用 Key かどうか。1 ははい、0 はいいえ。同一ワークスペース内で未削除の Owner Key は最大 1 つです。 |
| content.remark | string | 既存の備考。本 External の公開されている追加/変更パラメーターには remark は含まれません。 |
| content.isBurnAfterReading | integer | 保持されている閲覧後破棄フラグ。本モジュールは読み取り後の破棄を実行しないため、これに依存して認証情報を取り消さないでください。 |
| content.callCount | integer または null | 永続的な累計呼び出し回数。非同期集計であり、リアルタイムのカウントではありません。作成スナップショットは flush 前に null になる場合があります。 |
| content.lastCallAt | integer または null | 最終呼び出し Unix 秒。通常 -1 は記録なしを表します。作成スナップショットでは null になる場合があります。 |
| content.creatorInfo | object | 作成アイデンティティの要約。解析できない場合は {} で、フィールドはアイデンティティタイプによって変化します。 |
| content.creatorInfo.uuid | string | 作成アイデンティティ UUID。システムアイデンティティでは空になる場合があります。 |
| content.creatorInfo.status | integer | 作成アイデンティティの状態。 |
| content.creatorInfo.wsAccountStatus | integer | ワークスペース関係状態の要約。システムアイデンティティでは 0 になる場合があります。 |
| content.creatorInfo.username | string | ユーザー名またはシステムアイデンティティ名。 |
| content.creatorInfo.name | string | 表示名。 |
| content.creatorInfo.email | string | メールアドレスまたはシステムアイデンティティ識別子。 |
| content.creatorInfo.mobile | string | 携帯電話番号。システムアイデンティティでは空です。 |
| content.creatorInfo.countryCode | string | アカウントアイデンティティが提供できる携帯電話の国番号。システムアイデンティティでは省略される場合があります。 |
| content.creatorInfo.iconUrl | string | アカウントアイデンティティが提供できるアバター。システムアイデンティティでは省略される場合があります。 |
| content.creatorInfo.acntWsNickname | string | アカウントアイデンティティが提供できるワークスペースニックネーム。システムアイデンティティでは省略される場合があります。 |
| content.effectiveAccountUUID | string | 認可ロールの主体。手動 Key では Key 自身の uuid、アカウントバインド Key では accountUUID です。 |
| content.accountInfo | object または null | アカウントをバインドしている場合に、password/mfaSecret を除いたアカウント情報を返します。手動 Key では null です。 |
| content.accountInfo.id | integer | サイト内のアカウントレコード番号。情報返却のみに使用し、他の API 呼び出しでは uuid を使用します。 |
| content.accountInfo.uuid | string | アカウント UUID。以降の照会、変更、無効化、削除ではこのフィールドを使用します。 |
| content.accountInfo.status | integer | バインドされたアカウントの状態: 成功時は 0 またはその他の無効化されていない履歴状態を返す場合があります。2 の場合は先に ft.AgentMemberDisabled を発生させ、3 または存在しない場合は先に ft.AgentMemberNotFound を発生させます。 |
| content.accountInfo.creator | string | 作成アイデンティティ識別子。External による作成では通常 SYS です。 |
| content.accountInfo.updator | string | 最近の変更アイデンティティ識別子。まだ変更がない場合は空になることがあります。 |
| content.accountInfo.createAt | number | 作成時刻(Unix 秒)。 |
| content.accountInfo.updateAt | number | 更新時刻(Unix 秒)。更新時刻がまだない場合は -1 になることがあります。 |
| content.accountInfo.deleteAt | number | 状態操作時刻フィールド。初期値は通常 -1 です。有効化/無効化でもこの値が書き込まれるため、これだけに基づいて削除を判断せず、status を使用してください。 |
| content.accountInfo.name | string | 表示ニックネーム。 |
| content.accountInfo.username | string | ログインアカウント名。サードパーティアカウントでは空または他のアカウントと重複する場合があります。 |
| content.accountInfo.email | string | アカウントの連絡先メールアドレス。作成時に空で、username がメール形式の場合は username で補完されます。 |
| content.accountInfo.mobile | string | 携帯電話番号のローカル番号。復号して表示され、国番号は含みません。未設定の場合は空文字列です。 |
| content.accountInfo.countryCode | string | 携帯電話番号の国/地域コード(数字のみの文字列、例: 86)。未設定の場合は空文字列です。 |
| content.accountInfo.exterId | string | サードパーティ ID システムの一意 ID。ローカルアカウントでは通常空です。 |
| content.accountInfo.extend | object または null | バインドされたアカウントの既存拡張情報。user_icon のアバターアドレスを含む場合があります。本ページでは返却のみで、Key パラメーターから変更できません。 |
| content.accountInfo.extend.user_icon | string | 任意のアバター URL または静的リソースファイル名。履歴情報を読み取る際に現れる場合があり、本ページで書き込み可能なパラメーターではありません。 |
| content.accountInfo.source | string | アイデンティティソース識別子(例: local、unknown、oidc、ldap)。agent などの履歴上の内部ソースが存在する場合もあります。 |
| content.accountInfo.nameSpace | string | アイデンティティ名前空間。External による作成ではデフォルトで空です。本モジュールの公開パラメーターでは設定できません。 |
| content.accountInfo.isUsed | integer または boolean | アカウントが使用済みかどうかのフラグ。 |
| content.accountInfo.agreeTerms | integer | 規約同意フラグ。 |
| content.accountInfo.canaryPublic | boolean | カナリアフラグ。 |
| content.accountInfo.enableMFA | boolean | MFA を有効化しているかどうか。 |
| content.accountInfo.language | string | 言語識別子。zh、en、zh-hant、id、ja、ko。 |
| content.accountInfo.tokenHoldTime | integer | アカウントの無操作セッション保持時間(秒)。新規アカウントはサイトのセキュアセッション設定に従って初期化され、例の値に固定される保証はありません。 |
| content.accountInfo.tokenMaxValidDuration | integer | アカウントセッションの最大有効期間(秒)。新規アカウントはサイトのセキュアセッション設定に従って初期化されます。 |
| content.accountInfo.timezone | string | タイムゾーン識別子。未設定の場合は空です。 |
| content.accountInfo.attributes | object | SSO 同期属性の KV オブジェクト。後続の SSO ログインで上書きされる場合があります。キーと値は連携側の取り決めによります。 |
| content.accountInfo.attributes.{属性名} | 任意の JSON 値 | カスタム属性値。文字列の使用を推奨します(例: 部門=研究開発部)。 |
| content.accountInfo.customAttributes | object | 業務側で維持管理する属性 KV オブジェクト。 |
| content.accountInfo.customAttributes.{属性名} | 任意の JSON 値 | 業務カスタム値。文字列の使用を推奨します(例: costCenter=CC-1001)。 |
| content.accountInfo.statusPageSubs | integer | ステータスページ購読フラグ。 |
| content.accountInfo.defaultWorkspace | string | アカウントのデフォルトワークスペース UUID。未設定の場合は空です。 |
| content.accountInfo.brandKey | string | アカウントの現在のブランド識別子。サイトで許可されているブランドの集合によって決まります。 |
| content.accountInfo.scheduleMobile | string | シフト専用の携帯電話ローカル番号。未設定の場合は空です。 |
| content.accountInfo.scheduleEmail | string | シフト専用メールアドレス。未設定の場合は空です。 |
| content.accountInfo.ifScheduleMobileEnable | boolean | シフト用携帯電話番号を有効化しているかどうか。 |
| content.accountInfo.ifScheduleEmailEnable | boolean | シフト用メールアドレスを有効化しているかどうか。 |
| content.accountInfo.accountStatus | string | アカウントの追加状態識別子。未設定の場合は空です。 |
| content.roles | オブジェクト配列 | 現在有効なロールの要約。Owner 専用 Key では Owner ロールです。 |
| content.roles[].uuid | string | ロール UUID。 |
| content.roles[].name | string | ロール名。 |
| content.permissions | 文字列配列 | 現在有効な権限識別子。順序は保証されません。 |
| content.permissions[] | string | 1 つの有効な権限 ID。 |
| content.rolePermissions | object | ロール UUID をキーとする完全な有効権限マップ。 |
| content.rolePermissions.{角色UUID} | 文字列配列 | そのロールの現在有効な権限 ID リスト。動的ロールキーは roles[].uuid から取得します。 |
| content.rolePermissions.{角色UUID}[] | string | 単一の権限 ID。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例只读API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1,
"creatorInfo": {
"uuid": "",
"status": 0,
"name": "SYS",
"wsAccountStatus": 0,
"username": "SYS",
"email": "SYS",
"mobile": ""
},
"effectiveAccountUUID": "wsak_example001",
"accountInfo": null,
"roles": [
{
"uuid": "role_example001",
"name": "示例最小权限角色"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example001": [
"routine.defaultAccess"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
アカウントバインド Key の構造例(実際の権限はバインドされたアカウントによって変化します):
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例只读API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "acnt_example001",
"createdWay": "agent",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1,
"creatorInfo": {
"uuid": "",
"status": 0,
"name": "SYS",
"wsAccountStatus": 0,
"username": "SYS",
"email": "SYS",
"mobile": ""
},
"effectiveAccountUUID": "acnt_example001",
"accountInfo": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例Agent",
"username": "agent-example",
"email": "",
"mobile": "",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "agent",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部门": "研发部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": ""
},
"roles": [
{
"uuid": "role_example001",
"name": "示例最小权限角色"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example001": [
"routine.defaultAccess"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーの詳細は 共通エラー定義 を参照してください。
下表は確認済みのリクエストおよび業務分岐を示します。通常のデータベース/キャッシュ/監査の 5xx はグローバルラッパーにより ft.InternalServerError になります。書き込み API がエラーを返す場合、名前、Owner フラグ、ロール、または削除状態がすでに保存されている可能性があるため、まず現在の状態を照会してから次の手順を決定してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメーター解析失敗 | パラメーターの位置、フィールド名、型、値を確認してください。 |
| 404 | ft.AKNotExistOrDelete | UUID に対応する有効な非システム API Key が存在しない、または Key がすでに削除/無効化されている | 指定された AK が存在しないか、すでに削除されています | リストから対象の uuid を再取得してください。リストにはアカウントバインド Key が表示されず、システム組み込み Key はこのエントリから管理できない点に注意してください。 |
| 404 | ft.AgentMemberNotFound | バインドされたアカウント UUID に対応するアカウントが存在しない、またはすでに削除されている | agent に対応するユーザーが見つかりません | 対応するアカウント管理エントリでアカウントと Key のバインドを確認し、手動 Key として扱わないでください。 |
| 403 | ft.AgentMemberDisabled | バインドされたアカウントが無効化状態 | agent に対応するユーザーは無効化されています | 先に対応するアカウント管理フローで状態を処理してください。 |
| 404 | ft.WorkspaceAgentMemberNotFound | バインドされたアカウントに、そのワークスペースの有効な直接メンバー関係がない | この agent に対応するユーザーが見つかりません | 対応するアカウント/Agent 管理エントリでワークスペースメンバーのバインドを確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ障害、監査、または未処理のフィールド例外 | 内部エラー | traceId を保持し、Key の現在の名前、ロール、状態を確認してください。データが先にコミットされてから失敗する可能性があるため、500 だけに基づいて未反映と見なさないでください。 |