コンテンツにスキップ

作成



POST /api/v1/workspace/accesskey/add

概要

指定したワークスペースの API Key を作成し、ロールを関連付けます。

呼び出し前の確認と使用手順

w 権限を持つ External 認証情報が必要です。まずワークスペースがアクティブであることを確認し、対象ロールの UUID を取得します。常に空でない roleUUIDs を明示的に指定することを推奨します。省略すると管理者 Key が作成され、[] でも認証のフォールバックにより管理者権限が付与される可能性があります。作成は名前による冪等操作ではなく、同名が存在するとエラーになります。タイムアウトした場合は、まず一覧を確認して作成済みかどうかを確認してください。通常は Owner 以外のロールを使用します。現在の External 実装では owner も受け付けます。Owner 専用 Key のみを作成し、他のロール値は無視します。同一ワークスペース内で未削除の Owner Key は最大 1 件です。成功すると新しい認証情報とロールの概要を返します。id や呼び出し統計などの作成スナップショットフィールドは null になる場合があり、その後の詳細取得で永続化された情報を取得できます。

リクエストヘッダー

パラメータ名 型 必須 説明
X-Df-SVersion string 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを継続使用することはできません。
例: v20240417
取得または入力方法: 本ページの例ではこの固定バージョンを使用し、サンプルの署名アルゴリズムと組み合わせます。
X-Df-Access-Key string Y 本モジュールの一覧では r または w 権限を使用できます。その他のインターフェース(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 大文字のメソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を実行して hex ダイジェストを取得します。
例: <hmac-sha256-hex>
取得または入力方法: External API 署名認証に従い、対応する SK を使用して計算します。完全に実行可能なテンプレートは以下を参照してください。
X-Df-Timestamp string Y サイト設定の署名有効時間枠内である必要があり、例の時刻を再利用することはできません。
例: 1785427200
取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
roleUUIDs[*] string 単一のロール UUID 文字列です。ロールは対象ワークスペースの許可範囲に属している必要があります。
例: role_example001
取得または入力方法: ワークスペースロール一覧から対象ワークスペースの実際のロール uuid を取得します。明確な最小権限のカスタムロール、または組み込みの readOnly/general などを使用することを推奨します。
name string Y 必須の表示名です。最大 256 文字で、空でなく重複しない文字列を指定します。
null の許可: False
最大長: 256
例: 示例只读API Key
取得または入力方法: まず API Key 一覧 で対象ワークスペースの既存名称を確認します。
roleUUIDs array 省略可能です。省略時はデフォルトで wsAdmin 管理者ロールになります。確認済みの空でない最小権限ロールを明示的に渡すことを推奨します。明示的な [] では権限のない Key にはなりません。認証時、有効なロール関連付けがない場合は wsAdmin にフォールバックする可能性があるため、空配列で権限を剥奪することはできません。null は無効です。
null の許可: False
例: ["role_example001"]
取得または入力方法: ワークスペースロール一覧から対象ワークスペースの実際のロール uuid を取得します。明確な最小権限のカスタムロール、または組み込みの readOnly/general などを使用することを推奨します。
workspaceUUID string Y 作成対象ワークスペースの UUID として必須です。アクティブな status=0 の既存ワークスペースである必要があり、省略、空、または null にはできません。
null の許可: False
例: wksp_example001
取得または入力方法: ワークスペース一覧の content.data[].uuid から取得し、対象ワークスペースを確認します。

パラメータ補足

サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。本ページで生成されるワークスペース API Key と External 署名認証情報は別の認証情報です。External は現在 AK/SK を平文で返すため、フロントエンド画面のマスクポリシーは適用されません。レスポンス例はすべてプレースホルダー値を使用しているため、実際のレスポンスは認証情報として保管してください。本インターフェースには accountUUID、createdWay、remark、または閲覧後破棄などの公開入力パラメータはなく、アカウントに紐づく Key の作成には使用できません。

リクエスト例

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 = 'POST'
path = '/api/v1/workspace/accesskey/add'
query = {}
data = {'workspaceUUID': 'wksp_example001', 'name': '示例只读API Key', 'roleUUIDs': ['role_example001']}
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.roleInfo オブジェクト配列 作成時に関連付けられたロールの概要です。明示的な [] は [] を返す場合があり、これに基づいて有効な権限が空であると判断することはできません。
content.roleInfo[].uuid string ロール UUID。
content.roleInfo[].name string ロール名。
{
  "code": 200,
  "content": {
    "id": null,
    "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": null,
    "lastCallAt": null,
    "roleInfo": [
      {
        "uuid": "role_example001",
        "name": "示例最小权限角色"
      }
    ]
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラーレスポンス

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

以下の表に、確認済みのリクエストおよび業務分岐を示します。通常のデータベース/キャッシュ/監査の 5xx はグローバルラッパーにより ft.InternalServerError になります。書き込みインターフェースがエラーを返した場合でも、名前、Owner フラグ、ロール、または削除状態がすでに保存されている可能性があるため、まず現在の状態を照会してから次の操作を決定する必要があります。

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 処理方法
406 ft.ParameterValidationFailed リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています パラメータの解析に失敗しました パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効です リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正してください。
400 ft.JsonFormatError JSON のトップレベルがオブジェクトではありません 一部の json ファイルの形式エラー JSON オブジェクトを使用し、配列や null をリクエストボディ全体として使用しないでください。
401 ft.WKSPNotExistOrReleased 対象ワークスペースが存在しないか、アクティブな status=0 ではありません ワークスペースが存在しない/またはすでにリリースされています ワークスペース一覧から有効なワークスペースを選択してください。
400 ft.AKNameRepeat 対象ワークスペースに同名の未削除 API Key がすでに存在します 同名の AK がすでに存在します まず名前を照会してください。既存 Key を変更する必要がある場合は変更操作を使用し、重複作成を冪等成功として扱うことはできません。
400 ft.AKOnwerRepeat 同一ワークスペースに別の未削除 Owner Key がすでに存在します 所有者 AK がすでに存在します まず既存の Owner Key を確認してください。重複作成や同時権限昇格によって複数の Owner Key を作成しないでください。
400 ft.InvalidRoleUUID ロール UUID が対象ワークスペースの有効なロール集合に含まれていません 無効なロール UUID: {} 対象ワークスペースのロール一覧から再選択してください。変更インターフェースでは名前または Owner フラグがすでに保存されている可能性があるため、この 400 が返された後もまず現在の状態を読み取る必要があります。
500 ft.InternalServerError データベース、キャッシュ障害、監査、または未処理のフィールド例外 内部エラー traceId を保持し、Key の現在の名前、ロール、状態を確認してください。データは先にコミットされてから失敗する可能性があるため、500 のみに基づいて未反映と判断することはできません。

フィードバック

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