変更¶
POST /api/v1/workspace/accesskey/{ak_uuid}/modify
概要¶
API Key 名を変更し、その直接のロール関連付けを置き換えます。
呼び出し前と使用手順¶
External 認証情報の w 権限が必要です。name は必須であり、ロールのみを変更する場合でも現在の名前を送信してください。roleUUIDs を省略すると元のロール関連付けが保持されます。明示的な配列は完全な置き換えであり、追加ではありません。[] を使用して権限を剥奪しないでください。有効な関連付けがない場合、認証は wsAdmin にフォールバックする可能性があります。認証情報を取り消す必要がある場合は Key を削除してください。owner を含めると Owner 専用 Key に変換され、他の対象ロールは無視されます。ワークスペースごとに最大 1 件です。Owner から非 Owner の配列に切り替えると Owner フラグが解除されます。Agent に紐づくソース Key は変更できません。名前/Owner フラグが先にコミットされ、その後ロールの検証と更新が行われるため、InvalidRoleUUID などの 400 でも名前または Owner フラグが既に変更されている可能性があります。先に詳細を取得して現在の状態を確認してから再試行してください。この操作では ak/sk をローテーションしません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 権限を使用できます。その他のインターフェース(GET 詳細を含む)では、External 認証情報の 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 秒文字列を生成します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| roleUUIDs[*] | string | 単一のロール UUID 文字列です。ロールは対象ワークスペースで許可される範囲に属している必要があります。 例: role_example001取得・入力方法: ワークスペースロール一覧 から対象ワークスペースの実際のロール uuid を取得します。明確な最小権限のカスタムロール、または組み込みの readOnly/general などの使用を推奨します。 |
|
| name | string | Y | 必須です。最大 256 文字です。ロール変更時に名前を保持する場合も現在の値を送信する必要があります。null は使用できません。 null を許可: False 最大長: 256 例: 示例API Key新名称取得・入力方法: API Key 詳細 から現在の name を取得し、必要な場合にのみ新しい名前に変更します。 |
| roleUUIDs | array | 任意です。省略すると元の関連付けが保持されます。明示的な配列は完全置換です。[] は関連付けをクリアしますが、認証が管理者にフォールバックする可能性があるため、権限の剥奪には使用できません。owner は特別な権限昇格の意味を持つため、null は無効です。 null を許可: False 例: ["role_example001"]取得・入力方法: ワークスペースロール一覧 から対象ワークスペースの実際のロール uuid を取得します。明確な最小権限のカスタムロール、または組み込みの readOnly/general などの使用を推奨します。 |
パラメータの補足説明¶
サイトレベルの External API AK/SK を使用します。署名方式は External API 署名認証 を参照してください。本ページで生成されるワークスペース API Key と External 署名認証情報は別の認証情報です。External は現在 AK/SK の平文を返し、フロントエンド画面のマスクポリシーは適用されません。レスポンス例はすべてプレースホルダー値を使用しています。実際のレスポンスは認証情報として保管してください。変更後は、後続のリクエストが新しいロールで権限を再取得できるように、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 = 'POST'
path = '/api/v1/workspace/accesskey/wsak_example001/modify'
query = {}
data = {'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 | オブジェクト配列 | 今回返されるロール関連付けの概要です。Owner 変換などの分岐では [] になる場合があります。isOwnerRole と併せて詳細を呼び出し、有効な roles/permissions を確認してください。 |
| content.roleInfo[].uuid | string | ロール UUID。 |
| content.roleInfo[].name | string | ロール名。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "external",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427200,
"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,
"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 をリクエストボディ全体として使用しないでください。 |
| 404 | ft.AKNotExistOrDelete | UUID に対応する有効な非システム API Key が存在しない、または Key が削除/無効化されています | 指定された AK は存在しないか、削除されています | 一覧から対象の uuid を再取得してください。一覧にはアカウントにバインドされた Key が表示されないことに注意してください。システム組み込み Key はこの入口では管理できません。 |
| 400 | ft.AKNameRepeat | 対象ワークスペースに同名の未削除 API Key が既に存在します | 同名の AK が既に存在します | まず名前を確認してください。既存の Key を変更する場合は変更操作を使用し、重複作成を冪等な成功として扱わないでください。 |
| 400 | ft.AKOnwerRepeat | 同じワークスペースに別の未削除 Owner Key が既に存在します | 所有者 AK が既に存在します | 既存の Owner Key を確認してください。重複作成や同時権限昇格によって複数の Owner Key を作らないでください。 |
| 400 | ft.InvalidRoleUUID | ロール UUID が対象ワークスペースの有効なロール集合に含まれていません | 無効なロール UUID: {} | 対象ワークスペースのロール一覧から再選択してください。変更 API は名前または Owner フラグを先に保存している可能性があるため、この 400 が返された後も先に現在の状態を読み取る必要があります。 |
| 400 | ft.AgentWorkspaceAKCanNotModify | 対象が createdWay=agent かつアカウントにバインドされた Key です | agent にバインドされた API Key は変更できません | 対応する Agent/アカウントの機能で管理し、本インターフェースで名前やロールを変更しないでください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ障害、監査、または未処理のフィールド例外 | 内部エラー | traceId を保持し、Key の現在の名前、ロール、状態を確認してください。データは先にコミットされてから失敗する可能性があるため、500 のみに基づいて未適用と判断しないでください。 |