コンテンツにスキップ

取得



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 だけに基づいて未反映と見なさないでください。

フィードバック

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