現在のワークスペーストークンをローテーション¶
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 を提供します。 |