変更¶
POST /api/v1/workspace/inner_accesskey/{workspace_uuid}/refresh
概要¶
ワークスペース内蔵システムキーのAK/SKをリセットし、存在しない場合は新しいキーを作成します。
呼び出し前の確認と使用手順¶
w権限が必要です。まずワークスペース一覧でアクティブなワークスペースを確認し、次に内蔵キーの初期化と取得で現在のキーと依存先を確認します。このエンドポイント自体はワークスペースのアクティブ状態を再検証しません。キーが存在しない場合は直接作成されるため、任意のUUIDを渡してワークスペースの存在を探ることはできません。キーが存在する場合はレコードのuuidを保持し、AK/SKを再生成して更新時刻を更新します。存在しない場合はOwnerシステムキーを作成します。リクエストボディはなく、ttlの猶予時間や名前だけを変更するオプションもありません。更新のたびに新しい認証情報が生成され、冪等ではありません。失敗後はまず現在の認証情報を確認し、むやみに再更新しないでください。現在の実装では旧AKの認証キャッシュを明示的に無効化しますが、旧SKキャッシュを同時に明示的にクリアすることはありません。旧SKに有効な認証キャッシュがある場合、成功レスポンスだけをもって、すべての旧認証情報が直ちに失効したと判断することはできません。管理者がキャッシュ処理と実際の認証結果を確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | ワークスペースUUID。API KeyレコードUUIDや平文AK/SKではありません。 例: wksp_example001取得または入力方法: ワークスペース一覧のcontent.data[].uuidから取得し、サイトとアクティブ状態を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用しており、例の署名アルゴリズムと組み合わせて使用します。 |
|
| X-Df-Access-Key | string | Y | 本モジュールの一覧ではrまたはw権限を使用できます。その他の3項目(GET初期化を含む)にはw権限が必要です。 例: <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認証情報を使用します。認証についてはExternal API 署名認証を参照してください。一覧ではrまたはw権限を許可し、その他の3項目(GET初期化を含む)にはw権限が必要です。すべてのレスポンスで高権限の認証情報が平文で返される可能性があるため、通常のフロントエンドページのマスク表示ルールを適用しないでください。例ではプレースホルダー値を使用しており、実際の認証情報は安全に保管する必要があります。キーが存在しない新規作成分岐では、flush前に返却スナップショットを取得するため、id、callCount、lastCallAtがnullになる可能性があります。キーが存在する分岐では、元のレコード情報と新しい認証情報を返します。
リクエスト例¶
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/inner_accesskey/wksp_example001/refresh'
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 | 内蔵キーのステータス。本モジュールの照会および削除ではstatus=0を選択します。 |
| 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 | 内蔵キー名。初期化時はinnerです。 |
| content.ak | string | 内蔵システムAccess Keyの平文。高権限の認証情報として保管してください。External署名用AKではありません。 |
| content.sk | string | 内蔵システムSecret Keyの平文。高権限の認証情報として保管してください。External署名用SKではありません。 |
| content.workspaceUUID | string | 所属ワークスペースUUID。 |
| content.accountUUID | string | バインドされたアカウント識別子。初期化されたシステムキーでは通常空文字列です。 |
| content.createdWay | string | 作成元。初期化では通常manualです。システム範囲はisSystem/businessTypeで区別されます。 |
| content.businessType | string | 本モジュールはinner sysタイプのみを管理します。 |
| content.isSystem | integer | 本モジュールはシステム内蔵キーのみを管理し、初期化時は1です。 |
| content.isOwnerRole | integer | 初期化時は1で、Ownerロールの意味を持ちます。通常の手動Owner Keyとは別に管理されます。 |
| content.remark | string | 既存の備考。本モジュールには備考を変更するリクエストパラメータはありません。 |
| content.isBurnAfterReading | integer | 保持されている閲覧後破棄フラグ。本モジュールでは読み取り後の破棄を実行しないため、これに依存して認証情報を失効させないでください。 |
| content.callCount | integer または null | 永続的な累計呼び出し回数。非同期統計であり、リアルタイムのカウントではありません。作成スナップショットはflush前に取得されるため、nullになる可能性があります。 |
| content.lastCallAt | integer または null | 最終呼び出しUnix秒。通常-1は記録なしを表します。作成スナップショットではnullになる可能性があります。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_inner_example001",
"status": 0,
"creator": "external",
"updator": "external",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427200,
"name": "inner",
"ak": "<refreshed-inner-access-key>",
"sk": "<refreshed-inner-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "inner sys",
"isSystem": 1,
"isOwnerRole": 1,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
キーが存在しない場合に作成されるスナップショットの例:
{
"code": 200,
"content": {
"id": null,
"uuid": "wsak_inner_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "inner",
"ak": "<inner-access-key>",
"sk": "<inner-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "inner sys",
"isSystem": 1,
"isOwnerRole": 1,
"remark": "",
"isBurnAfterReading": 0,
"callCount": null,
"lastCallAt": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
パラメータが宣言に適合しない場合は共通リクエストエラーを返します。データベース、キャッシュなどの通常の内部例外は最終的に500 ft.InternalServerErrorに統一されます。書き込みリクエストが失敗した後は、まず永続状態とキャッシュを確認してください。すべてが反映されていないことは保証されません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落している、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュの失効、または明示的に処理されていない内部例外 | 内部エラー | traceIdを保存し、まずキーの現在の状態と実際の呼び出し結果を確認してから再試行を判断してください。データベースはすでにコミットされている可能性があるため、エラー応答だけで変更がないと判断することはできません。 |