コンテンツにスキップ

現在のワークスペーストークンをローテーション



POST /api/v1/workspace/token/rotate

概要

現在のワークスペースのデフォルト収集トークンをローテーションし、旧値の猶予期間を設定します。

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

現在のワークスペースで workspace.tokenReplace 権限を持つ OpenAPI Key を使用し、まず収集側とデフォルトトークンを使用する連携を洗い出します。ここでは収集認証情報を交換するものであり、OpenAPI API Key をローテーションするものではありません。ttl は旧値の残存有効期間を制御します。0s は旧値を直ちに無効化し、その他の値は最大 24 時間です。新しい値はデフォルトの長期認証情報のセマンティクスを維持し、openDataQuery を引き継ぎます。

成功後は新しいトークンを保存し、外部の収集側を更新します。システム内のデフォルトトークン参照は同期に伴って更新されますが、外部で独自に保存した値は自身で置き換える必要があります。ローテーションのたびに新しい値が生成され、24 時間のクールダウン中は再ローテーションできず、冪等性はありません。いずれかのワークスペーストークンの同期が pending の場合、この操作がブロックされる可能性があります。

OperationBusy/SyncPending など content.committed を含む 409 分岐では、このフィールドを確認する必要があります。false は今回保存されていないことを示すため、ロック/既存の同期を処理してから再リクエストします。true は新しい値に交換済みであることを示すため、検証/同期の補完を行う必要があり、重複してローテーションしてはいけません。Cooling/Revoked には committed が含まれない場合があり、欠落を false とみなしてはいけません。具体的な errorCode に応じて処理します。syncRequiresVerification=true の場合は、まず下流の実際の結果を検証し、盲目的に再実行しないでください。レスポンスが失われた場合は、管理者がワークスペーストークン管理から現在の認証情報と同期状態を確認してから、収集側を更新してください。成功レスポンスには no-store/no-cache が付与されるため、認証情報のキャッシュを避けてください。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
ttl string Y 必須。0s または正の整数+小文字の s/m/h/d。先頭に 0 を付けず、空白/大文字/null/小数は受け付けません。実際の合計秒数は 86400 を超えることはできません。ttl は新しい値の有効期間ではありません。
null を許可: False
$matchRegExp: ^(0s|[1-9][0-9]*[smhd])$
例: 30m
取得または入力方法: 収集設定に応じた置換ウィンドウとして 0s/30m/1h/24h/1d などを選択します。

パラメータ補足説明

対象は常に現在のワークスペースのデフォルト収集トークンであり、チームトークンや OpenAPI Key は管理しません。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/workspace/token/rotate' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"ttl":"30m"}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。

フィールド 型 説明
content.token string 新しいデフォルト収集トークンの平文。安全に保存してください。OpenAPI Key ではありません。
content.openDataQuery boolean 元のトークンのデータクエリ権限を引き継ぎます。
content.declaration object または null 現在のワークスペースの共通宣言。
content.committed boolean 一部の 409 エラーのみ。true は変更が保存済み、false は今回保存されていないことを示します。
content.nextRotateAt integer Cooling 409 のみ。次回ローテーションが許可される Unix 秒。
content.syncStatus string 同期 409 のみ。通常は pending。
content.syncRequiresVerification boolean 一部の同期 409。true の場合は先に下流の結果を検証する必要があります。
content.syncFailureReason string 一部の 409 の理由。例: operation_busy/cache_pending/verification_required/kodo_failed。
content.tokenRecordUUID string または null 一部の同期 409。デフォルトトークンでは通常 null で、認証情報の平文ではありません。
content.isDefault boolean 一部の同期 409。このエントリでは true です。
レスポンスヘッダー 型 説明
Cache-Control string 成功レスポンスは no-store。
Pragma string 成功レスポンスは no-cache。
{
  "code": 200,
  "content": {
    "token": "<NEW-WORKSPACE-TOKEN>",
    "openDataQuery": false,
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

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

HTTP ステータス errorCode 発生条件 メッセージまたはレスポンスの説明 対処方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認します。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON の形式エラー content.reason、line、column に従って JSON を修正します。
400 ft.JsonFormatError JSON のトップレベルがオブジェクトではない 一部の json ファイル形式エラー このページのパラメータに従って JSON オブジェクトを送信します。
401 ft.WKSPNotExistOrReleased 現在のワークスペースが存在しない、または status!=0 ワークスペースが存在しない/または解放済み 現在のワークスペースがアクティブであることを確認します。
404 ft.ObjectNotExists ワークスペースのデフォルトトークンレコードが存在しない 指定されたオブジェクトが存在しない 管理者にトークンレコードの修復を依頼してください。このエントリを使用して作成しないでください。
400 ft.WorkspaceTokenInvalidTTL 宣言形式は通過したが、合計猶予期間が 24 時間を超えている 旧値の有効期間は 24 時間を超えられません 24 時間以内に変更してください。直ちに無効化する場合は 0s を使用します。
409 ft.WorkspaceTokenCooling 前回のローテーションから 86400 秒未満(過去のクールダウンを含む) 再生成可能な時刻に達していません content.nextRotateAt(Unix 秒)を読み取って待機し、高頻度で再試行しないでください。
409 ft.WorkspaceTokenRevoked デフォルトトークンが無効化済み/状態異常/長期有効な認証情報ではない トークンは無効化済み、または使用できません 管理者が現在のデフォルト認証情報の状態を確認します。
409 ft.WorkspaceTokenOperationBusy 同一ワークスペースのライフサイクル相互排他が他の操作に占有されている 現在のワークスペースで他の操作が進行中です。今回の操作は保存されていません。しばらくしてから再試行してください。 committed=false の場合は、まずロックの解放を待ってから現在の状態を確認します。
409 ft.WorkspaceTokenSyncPending 既存の同期待ちレコード/前回結果の検証待ち、または今回のコミット後に同期が失敗 分岐のヒントに従い、今回未保存または変更保存済み content.committed で区別します。コミット済みの場合は検証/同期の補完のみを行い、syncRequiresVerification=true の場合は先に下流を検証します。
500 ft.InternalServerError データベース、キャッシュ/キュー、下流の通常の 5xx/タイムアウト、または未処理タイプの失敗。書き込みがすでにコミットされている可能性があります 内部エラー まず現在/対象ワークスペースの詳細と下流の状態から保存済みの結果を確認し、盲目的に作成/ローテーションを繰り返さないでください。保存済みの場合は未完了の同期のみを処理し、traceId を提供します。
{
  "code": 409,
  "content": {
    "committed": true,
    "syncStatus": "pending",
    "tokenRecordUUID": null,
    "isDefault": true
  },
  "errorCode": "ft.WorkspaceTokenSyncPending",
  "message": "变更已保存,但同步尚未完成,请先处理同步问题,无需重复提交本次操作。",
  "success": false,
  "traceId": "TRACE-EXAMPLE"
}

フィードバック

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