作成¶
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 のみに基づいて未反映と判断することはできません。 |