ワークスペース Token のローテーション¶
POST /api/v1/workspace/{workspace_uuid}/token/rotate
概要¶
指定したワークスペースのデフォルト収集 Token をローテーションし、旧値に短期間の猶予時間を設定します。
呼び出し前の確認と使用手順¶
まず、デフォルト Token を使用している収集側および連携を洗い出し、置換を完了するのに十分な旧値の有効期間を選択します。ttl は旧 Token の残存有効期間を制御するものであり、新 Token の有効期間ではありません。成功後は content.token を安全に保存し、収集設定を更新します。デフォルト認証情報の参照は同期処理に伴って処理されますが、外部で独自に保存した Token は引き続き自身で置換する必要があります。この API は呼び出しごとに新しい認証情報を生成するため冪等性はなく、24 時間以内にローテーションを繰り返すことはできません。失敗時は必ず content.committed を確認してください。保存済みの場合は同期を処理し、ローテーションを継続することはできません。レスポンスが失われた場合は、管理者がワークスペース Token 管理から現在値と同期状態を確認してから続行してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | ターゲットワークスペースの UUID。アカウント UUID でも収集 Token でもありません。 例: wksp_example001取得または入力方法: ワークスペース一覧の content.data[].uuid、または作成成功時の content.wsInfo.uuid から取得し、サイトとワークスペース名を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | サンプルと一致させる必要があり、省略したままこのアルゴリズムを使い続けることはできません。 例: v20240417取得または入力方法: 本ページの元のパスおよびリクエストボディの署名アルゴリズムに対応して入力します。 |
|
| X-Df-Access-Key | string | Y | ここでは 7 項目すべてが書き込み操作であるため、External の書き込み権限が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が w 権限を持つ 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>取得または入力方法: 対応する SK を使用し、External API 署名認証および下部の Python テンプレートに従って計算します。 |
| X-Df-Timestamp | string | Y | サンプルの固定時刻を再利用することはできません。サイトの署名有効ウィンドウ内に収める必要があります。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) で現在の Unix 秒を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| ttl | string | Y | 必須の文字列で、0s または正の整数 + 小文字の s/m/h/d のみを受け付けます。0s は旧値を即時に無効化することを示し、それ以外の値は旧値の残存猶予期間で、24 時間を超えることはできません。空白、null、小数、大文字の単位は受け付けません。 null 許容: False $matchRegExp: ^(0s|[1-9][0-9]*[smhd])$ 例: 30m取得または入力方法: 収集側の置換ウィンドウに応じて 0s、30m、1h、24h、1d などを選択します。最大 86400 秒です。 |
パラメータ補足説明¶
w 権限を持つサイトレベルの External API 認証情報を使用します。認証方式はExternal API 署名認証を参照してください。サンプルは v20240417 に従って署名を計算し、署名と送信には同じパス、Query、元のリクエストボディを使用します。すべてのサンプルはデモ用の値であり、実行前に実際のターゲットに置き換えてください。書き込みリクエストがタイムアウトまたは 500 になった場合は、まず現状を照会し、確認してから再試行するかどうかを決定します。
リクエスト例¶
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/wksp_example001/token/rotate'
query = {}
data = {'ttl': '30m'}
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 を自動注入しません。ワークスペースオブジェクト内の declaration はそれ自体が保持するフィールドです。
| フィールド | 型 | 説明 |
|---|---|---|
| content.token | string | 新しいデフォルト収集 Token の平文。今回のみ返されるため安全に保存する必要があります。External API AK ではありません。 |
| content.openDataQuery | boolean | 現在の Token のデータクエリ権限フラグ。ローテーション時は元の権限を引き継ぎます。 |
| content.committed | boolean | 一部の 409 エラー時のみ返されます。true は新 Token が保存済み、false は今回まだ保存されていないことを示します。 |
| content.nextRotateAt | integer | クールダウン 409 エラー時のみ返されます。次回ローテーションが許可される Unix 秒の時刻です。 |
| content.syncStatus | string | 同期 409 エラー時のみ返され、通常は pending です。 |
| content.syncRequiresVerification | boolean | 一部の同期エラーで提供されます。true の場合は先に下流の結果を検証する必要があります。 |
| content.syncFailureReason | string | 一部の同期エラーで提供されます。例: operation_busy、cache_pending、verification_required、kodo_timeout、kodo_failed。 |
| content.tokenRecordUUID | string または null | 一部の同期エラーで提供されます。デフォルト Token の場合は通常 null です。 |
| content.isDefault | boolean | 一部の同期エラーで提供されます。この API の対象はデフォルト Token であり、値は true です。 |
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Cache-Control | string | 成功レスポンスは no-store です。 |
| Pragma | string | 成功レスポンスは no-cache です。 |
{
"code": 200,
"content": {
"token": "<new-workspace-token>",
"openDataQuery": false
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
下表は本 API の業務検証および確認済みの主なエラー分岐を一覧にしたものです。下流サービスは具体的なエラーに応じたマッピングにより他の 4xx エラーを返す場合があります。通常の 5xx および未知の例外はグローバル処理により ft.InternalServerError を返します。書き込みリクエストは、現在の設定とエラー content を組み合わせて有効になったかどうかを判断する必要があり、HTTP ステータスだけでロールバックを推測することはできません。
| 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 ではない | ワークスペースが存在しない/または解放済み | 一覧からワークスペースのアクティブ状態を確認します。 |
| 404 | ft.ObjectNotExists | ワークスペースの現在のデフォルト Token レコードが欠落 | 指定されたオブジェクトが存在しない | 管理者にこのワークスペースの Token レコードを修復してもらってください。この API を使用して代替レコードを作成しないでください。 |
| 400 | ft.WorkspaceTokenInvalidTTL | 形式は有効だが旧値の猶予時間が 24 時間を超えている | 旧値の有効期間は 24 時間を超えることはできません | 0s で即時無効化するか、24 時間を超えない有効期間を使用します。 |
| 409 | ft.WorkspaceTokenCooling | 前回のローテーションから 24 時間未満(旧エントリが保持するクールダウン時間を含む) | まだ再生成可能な時刻に達していません | content.nextRotateAt を読み取り、その Unix 秒の時刻を過ぎてからリクエストしてください。継続的に再試行しないでください。 |
| 409 | ft.WorkspaceTokenRevoked | デフォルト Token が無効化済み、期限切れ、または使用不可 | Token が無効化済みまたは使用不可 | 管理者にワークスペースの現在の認証情報状態を確認してもらってください。ローテーションを認証情報の復旧手段として扱わないでください。 |
| 409 | ft.WorkspaceTokenOperationBusy | ワークスペースのライフサイクルロック取得時に他の操作が既に存在 | 現在のワークスペースで他の操作が進行中です。今回の操作は保存されていません。しばらくしてから再試行してください。 | content.committed=false の場合は、後で新しい署名で再試行できます。 |
| 409 | ft.WorkspaceTokenSyncPending | 既に同期が保留中、またはローテーション送信後に Kodo との同期が未完了/結果が検証待ち | 分岐に応じて「今回の操作は保存されていません」または「変更は保存されました」と表示されるため、必ず content.committed と組み合わせて判断する必要があります | committed=true は既にローテーション済みであることを示すため、ローテーションを繰り返さないでください。管理者はまず Kodo の状態を検証し、その後でコミット済みの現状を同期します。syncRequiresVerification=true の場合は先に検証し、盲目的に再実行しないでください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、リソースサービス、または未処理のパラメータ変換例外 | 内部エラー | traceId を保存して管理者に連絡してください。まず設定と下流の実際の状態を照会し、失敗レスポンスを直接「保存されていない」と見なさないでください。また、盲目的に作成やローテーションを繰り返さないでください。 |
コミット済みだが下流の同期に失敗した例(HTTP 409、再ローテーション不可):
{
"code": 409,
"content": {
"committed": true,
"syncStatus": "pending",
"syncFailureReason": "kodo_failed",
"syncRequiresVerification": false,
"tokenRecordUUID": null,
"isDefault": true
},
"errorCode": "ft.WorkspaceTokenSyncPending",
"message": "変更は保存されましたが、Kodo インターフェースの呼び出しによる同期に失敗しました。今回の操作を再送信する必要はありません。同期を再試行してください。",
"success": false,
"traceId": "TRACE-EXAMPLE"
}