ワークスペースリソースのエクスポート¶
POST /api/v1/workspace/resource/export/task/create
概要¶
現在のワークスペースのリソース設定の ZIP エクスポートタスクを作成します。
呼び出し前の準備と使用手順¶
現在の Key には workspace.setManage が必要です。タスクは現在のワークスペースと、発行した Key のリソース UUID にのみ属します。同じワークスペースの別の Key は、同じロールであってもこのタスクを読み取り/キャンセルできません。同じ Key をローテーションしてもリソース UUID は保持されるため、taskId と API Key の値を混同しないでください。
Body は不要です。または {} を送信してください。空でない JSON オブジェクトは拒否されます。resourceType/sloUUIDs を渡したり、エクスポートするモジュールの一部を指定したりすることはできません。SLO 専用のエクスポートには専用のインターフェースを使用してください。対応カタログに従って、ダッシュボード、モニター、エクスプローラー、通知先、SLO、セキュリティモニタリング、アラートポリシー、データ転送、ワークスペース属性クレーム、フィールド設定、タグ、環境変数、ロール、ログインデックス、ブラックリスト、Pipeline、正規表現、フィールドマスキングルール、機密データスキャンルールなどの設定のエクスポートを試みます。ログやメトリクスなどの生のビジネスデータは含まれず、データベース全体のバックアップでもありません。
成功時は taskId のみを返します。リソースタスクの進捗 を使用してポーリングしてください。status=ok になった後でのみ url が存在する可能性があります。import_info.exportInfo.result、exportFailedInfo およびリソース失敗サマリーを同時に確認する必要があります。ok は一部のリソースが権限またはシリアライズの失敗によりスキップされたことを意味する場合があり、すべてのオブジェクトがパッケージに含まれることを保証しません。タスク作成時の権限コンテキストを保存し、カスタム操作権限で制御される一部のリソースはルールに従ってフィルタリングされます。
リソースパッケージには、復元可能な外部ストレージのアクセスキー、接続設定、環境変数などの機密設定が含まれる場合があります。機密バックアップとして保管し、ダウンロード URL を公開しないでください。タスクと一時ファイルには有効期限があり、コードのデフォルトではタスクキャッシュは約 10 分で、サイトごとに設定可能です。ok 後はできるだけ早くダウンロードしてください。キャッシュが完全に存在しない場合は status=null が確認できます。ロングタスクがキャッシュの期限を超えると、帰属情報が欠けた状態レコードが残り 403 を返す場合があります。taskId を保持して管理者にタスクログ/リソースを確認してもらい、再作成するかどうかを決定してください。タスクの作成は冪等ではありません。ネットワーク障害が発生した場合は、まず返された taskId を確認してから再試行してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
パラメータ補足説明¶
1. インターフェースの用途
現在のワークスペースのリソースエクスポートタスクを開始します。
このインターフェースは非同期タスクインターフェースです。呼び出しに成功すると taskId のみが返され、圧縮パッケージの内容はすぐには返されません。
呼び出しの流れは次のとおりです:
- 現在のインターフェースを呼び出して
taskIdを取得します GET /api/v1/workspace/resource/query_action_statusを呼び出してタスクのステータスをポーリングします- ステータスが
okになったら、ステータスインターフェースの返却結果からエクスポートファイル情報を取得します
2. リクエストの説明
デフォルトでは、リクエストボディを送信しない場合、DF-API-KEY が属するワークスペースのすべてのリソースをエクスポートします。
SLO リソースパッケージをエクスポートする場合は、POST /api/v1/slo/export/task/create を呼び出してください。現在のインターフェースはワークスペースの全リソースのエクスポートにのみ使用されます。
3. レスポンスの説明
成功時の返却例:
説明:
- タスクの作成に成功した時点で
taskIdが返されます - その後のエクスポート実行の失敗、一部リソースのエクスポート失敗は、タスクステータスインターフェースで確認する必要があります
4. 現在のリソース境界の説明
現在のワークスペースのリソースのインポート/エクスポートには次の境界があります:
- 環境変数には
scope=rumは含まれません - ログインデックスには外部インデックスと
defaultは含まれません - フィールド管理はワークスペースのカスタムフィールドのみを処理します
- データアクセスは現在、ワークスペースのインポート/エクスポートをサポートしていません
5. エクスポート結果の補足説明
リソース内の単一のオブジェクトのエクスポートに失敗しても、エクスポートタスク全体は中断されません。
タスクステータスインターフェースの import_info.exportInfo.resourceFailureInfo は、重複を除いたリソースレベルの失敗明細を返します。これにはリソースタイプ、リソース UUID、リソース名、安定した失敗理由、および影響を受ける SLO が含まれます。リソース設定、権限メンバー、例外スタック、機密フィールドは返しません。
旧来の import_info.exportFailedInfo は旧クライアントとの互換性のために引き続き保持されますが、含まれる生の例外情報を直接表示することは推奨されません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/resource/export/task/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.taskId | string | 非同期タスク ID。後続で taskId を使用して照会/キャンセルします。ZIP のダウンロードアドレスや Celery の実行完了フラグではありません。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"taskId": "resource_task_example",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 400 | ft.ParamsValidateError | 空でない JSON オブジェクトを送信した場合。このエントリポイントはフィルタ付きエクスポートパラメータを受け付けません | パラメータ検証失敗: {} | Body を省略するか {} を送信してください。SLO 専用パラメータを混在させないでください。 |
| 500 | ft.InternalServerError | タスクキャッシュ/キュー、ファイルシステム、データベース、または未処理のタスクステータス/JSON 処理の失敗 | 内部エラー | まず同じワークスペース・同じ Key でタスクおよびリソースの現状を照会し、キューに登録済み/一部保存済みでないことを確認してから再試行してください。やみくもにインポートを繰り返したり上書きしたりしないでください。 |