ワークスペースリソースタスクステータスの照会¶
GET /api/v1/workspace/resource/query_action_status
概要¶
現在のワークスペースで自身が作成したリソースのインポート/エクスポートタスクの進捗を照会します。
呼び出し前の条件と使用手順¶
本エントリで許可されている routine.defaultAccess 権限のみを必要とし、元のタスク作成時の Key とワークスペースを使用します。taskId を使用してポーリングします。キャッシュが完全に存在しない場合は、通常どおり HTTP 200、content.status=null を返し、404 は返しません。ロングタスクの期限切れ後、ステータスの書き込みによって所有情報が欠落した不完全なキャッシュが再作成され、403 が返されることがあります。この 403 を、誤った Key に切り替えたことだけによるものと解釈してはいけません。権限なしで、存在する他人のタスクまたは他のワークスペースのタスクにアクセスした場合は 403 を返します。ロングタスクの不完全なキャッシュも 403 を引き起こす可能性があります。taskId を保持して管理者に連絡し、確認してください。
status=start/running の場合は待機を続けます。ok/error/cancel はフェーズステータスですが、error_code と import_info も同時に確認する必要があります。エクスポートの ok は部分成功の可能性があるため、exportInfo.result および失敗の詳細を確認してから、速やかに url をダウンロードしてください。インポートの ok でも、失敗/変換/スキップまたは noJsonDataError が存在する場合があるため、項目ごとに受け入れ確認を行う必要があります。recover をむやみに再実行せず、まず正常に保存されたリソースを確認してください。
一部の非同期エラーは照会時に非2xx に変換されます。fileContentError は JSON 形式エラーに変換され、登録済みの ft.* はそれぞれのビジネスステータスに従って返されます(通常の 5xx は 500 としてラップされます)。インポートの failedItems に一致する error_code がある場合、このルートは強制的に HTTP 400 を返し、ビジネス errorCode/message を保持します。エラーの content には status/action/error_code/import_info も含まれ、その中に成功件数が同時に含まれる場合があります。エラーまたはキャンセル時に全体がロールバックされることは保証されません。タスクキャッシュのコードはデフォルトで 600 秒で、実際のサイトで上書きされる場合があります。キャッシュ TTL は作成時にのみ設定され、後続のステータスでは更新されません。期限切れ/不完全なキャッシュの場合は、タスクログと把握済みの結果に基づいてリソースを照合したうえで、再作成するかどうかを決定してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| taskId | string | Y | 必須の空でないタスク ID。タスク作成時と同じワークスペース、同じ Key のリソース ID を使用する必要があり、ファイル名ではありません。 null を許可: False 例: resource_task_example取得または入力方法: リソースタスクのエクスポートまたはリソースパッケージのインポートのレスポンスの content.taskId から取得します。 |
パラメータ補足説明¶
タスク結果は、本ページの status、error_code および import_info フィールドを基準とします。短期間有効な ZIP ダウンロードアドレスを他の Studio API アドレスに変換する必要はありません。完全な URL は機密性の高いバックアップアドレスとして保管してください。部分成功時に全体がロールバックされることはないため、完了したリソースは読み戻して受け入れ確認してください。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/workspace/resource/query_action_status' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode taskId=resource_task_example
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.status | string または null | start はキュー待ち、running は実行中、ok は終了、error は異常、cancel はキャンセル要求を意味します。キャッシュが完全に存在しない場合は null になり、期限切れ後の不完全なステータスレコードでは 403 になる可能性があります。ok でもエラーと部分成功の概要を確認する必要があります。 |
| content.action | string | export または import。キャッシュが存在する場合に返されます。 |
| content.error_code | string または null | 非同期ビジネスエラーコード。ft.* または fileContentError/noJsonDataError の可能性があります。一部の登録済みエラーは今回の非2xx レスポンスに変換されます。エラーの説明を参照してください。 |
| content.import_info | object | 歴史的に踏襲されたフィールド名で、エクスポート/インポートのいずれもこれを使用してタスクのサマリーを格納します。 |
| content.url | string | export かつ status=ok の場合にのみ ZIP ダウンロード URL を返します。ダウンロード可能であっても、すべてのリソースがエクスポート済みであることを意味せず、永続的なバックアップ URL でもありません。 |
| content.noJsonDataImported | string | error_code=noJsonDataError の場合のローカライズされた説明およびローカライズされた通知。キャンセル/中断により外側が実際の完了件数を取得できなかった場合にも表示されることがあり、書き込みがなかったことを証明するものではないため、リソースを確認する必要があります。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
| content.import_info.successCount | integer | インポーターが集計した成功リソース数。省略される場合があり、下流の同期がすべて成功したことを証明するものではありません。 |
| content.import_info.failCount | integer | 集計された失敗項目数。部分失敗のカウント範囲はリソースタイプによって異なり、省略される場合があります。 |
| content.import_info.skippedCount | integer | 明示的にスキップされた数。省略される場合があります。 |
| content.import_info.failedItems | array<object> |
ビジネス上の失敗の詳細(ログインデックスの移行など)。省略される場合があります。 |
| content.import_info.failedItems[].resourceType | string | リソースタイプ。 |
| content.import_info.failedItems[].fileName | string | ソース設定ファイル名。 |
| content.import_info.failedItems[].name | string | リソース名。 |
| content.import_info.failedItems[].errorCode | string | サニタイズして正規化したビジネスコード。今回の HTTP デフォルト登録ステータスと同一とは限りません。 |
| content.import_info.failedItems[].message | string | サニタイズされたビジネスエラーメッセージ。 |
| content.import_info.convertedItems | array<object> |
ストレージ/スキーマ移行の変換記録。省略される場合があります。 |
| content.import_info.convertedItems[] | object | リソース移行変換のサマリー。タイプによって異なります。 |
| content.import_info.skippedItems | array<object> |
未サポートのスキーマなどによるスキップ記録。省略される場合があります。 |
| content.import_info.skippedItems[].resourceType | string | リソースタイプ。 |
| content.import_info.skippedItems[].fileName | string | ソースファイル名。 |
| content.import_info.skippedItems[].name | string | スキップされたリソース名。 |
| content.import_info.skippedItems[].reason | string | スキップ理由(例: unsupportedIndexMode)。 |
| content.import_info.skippedItems[].errorCode | string | 対応するビジネスコード。省略される場合があります。 |
| content.import_info.skippedItems[].message | string | スキップに関するビジネス説明。省略される場合があります。 |
| content.import_info.authFailedCrossWsInfo | array<object> |
クロスワークスペースリソースの認可失敗情報。省略される場合があり、タスクは部分成功となる可能性があります。 |
| content.import_info.authFailedCrossWsInfo[] | object | 失敗した関連オブジェクトの情報。 |
| content.import_info.skippedTags | array<object> |
インポート時にタグのスコープなどによってスキップされたサマリー。省略される場合があります。 |
| content.import_info.skippedTags[] | object | スキップされたタグ情報。タグインポートのサマリー構造に従います。 |
| content.import_info.exportFailedInfo | object | エクスポートモジュールのエラーマッピング。部分成功の可能性があり、値はそのリソースタイプのエラー文字列配列です。 |
| content.import_info.exportFailedInfo.资源类型 | array<string> |
あるリソースタイプのエクスポートエラー一覧。 |
| content.import_info.exportFailedInfo.资源类型[] | string | モジュールのエラーメッセージ。 |
| content.import_info.exportInfo | object | エクスポートの完全性サマリー。省略される場合があります。 |
| content.import_info.exportInfo.result | string | complete/partial。SLO 共有クエリでは empty になる場合もあります。ok から complete を推測しないでください。 |
| content.import_info.exportInfo.requestedSloCount | integer | SLO 専用のリクエスト数。ワークスペース全体のエントリでは通常 0 です。 |
| content.import_info.exportInfo.exportedSloCount | integer | 専用 SLO の実際のエクスポート数。ワークスペース全体では通常 0 です。 |
| content.import_info.exportInfo.skippedSloCount | integer | 専用 SLO のスキップ数。 |
| content.import_info.exportInfo.candidateResourceCount | integer | 集計済みの候補リソース数。 |
| content.import_info.exportInfo.exportedResourceCount | integer | 集計済みのエクスポート済みリソース数。 |
| content.import_info.exportInfo.permissionDeniedResourceCount | integer | 権限拒否されたリソース数。 |
| content.import_info.exportInfo.permissionDeniedByType | object | リソースタイプ別の拒否数。 |
| content.import_info.exportInfo.permissionDeniedByType.资源类型 | integer | そのタイプの拒否数。 |
| content.import_info.exportInfo.affectedSloCount | integer | 依存関係の失敗によって影響を受けた SLO 数。 |
| content.import_info.exportInfo.otherSkippedResourceCount | integer | その他のスキップ数。 |
| content.import_info.exportInfo.resourceFailureInfo | object | 完全なリソース失敗理由のグループ。 |
| content.import_info.exportInfo.resourceFailureInfo.schemaVersion | integer | 現在の値は 1。 |
| content.import_info.exportInfo.resourceFailureInfo.totalCount | integer | 失敗詳細数。 |
| content.import_info.exportInfo.resourceFailureInfo.permissionDeniedCount | integer | 権限関連の失敗数。 |
| content.import_info.exportInfo.resourceFailureInfo.otherCount | integer | その他の失敗数。 |
| content.import_info.exportInfo.resourceFailureInfo.byReason | object | 理由コード→件数。 |
| content.import_info.exportInfo.resourceFailureInfo.byReason.原因码 | integer | その理由の件数。 |
| content.import_info.exportInfo.resourceFailureInfo.items | array<object> |
リソース単位の失敗詳細。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].resourceType | string | リソースタイプ。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].resourceUUID | string または null | ソースリソース UUID。null を許可。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].resourceName | string または null | 表示名。null を許可。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].reasonCategory | string | permission または other。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].reasonCode | string | permission_denied/serialize_failed などの理由コード。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList | array<object> |
影響を受ける SLO 一覧。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList[].sloUUID | string | SLO UUID。 |
| content.import_info.exportInfo.resourceFailureInfo.items[].affectedSloList[].sloName | string または null | SLO 名。null を許可。 |
| content.import_info.convertedItems[].resourceType | string | 変換対象のリソースタイプ。 |
| content.import_info.convertedItems[].fileName | string | 変換元の設定ファイル。 |
| content.import_info.convertedItems[].name | string | 変換インデックス名。 |
| content.import_info.convertedItems[].field | string | 変換フィールド。現在は isFullLineIndex。 |
| content.import_info.convertedItems[].from | JSON | 元のスキーマ値。例: 0。 |
| content.import_info.convertedItems[].to | JSON | 新しいスキーマ値。例: 1。 |
| content.import_info.skippedItems[].indexName | string | 具体的に未サポートのスキーマのソース/クローンインデックス名。 |
| content.import_info.skippedTags[].name | string | スキップされたタグ名。 |
| content.import_info.skippedTags[].scope | array | タグの実際の scope 配列。 |
| content.import_info.skippedTags[].scope[] | string | 個別スコープ all/scene/monitor/dialing/security/infrastructure/catalog。 |
| content.import_info.authFailedCrossWsInfo[].name | string | 照会/参照されるソースワークスペース名。 |
| content.import_info.authFailedCrossWsInfo[].uuid | string | ソースワークスペース UUID。 |
| content.import_info.authFailedCrossWsInfo[].checkerName | string | クロスワークスペースクエリに関係するモニター名。 |
| content.import_info.skippedTags[].expectedScope | string | 今回のリソースに必要なタグスコープ。 |
| content.import_info.skippedTags[].reason | string | スキップ理由 scope_mismatch。 |
| content.import_info.skippedTags[].resourceUUID | string | 関連リソース UUID。省略される場合があります。 |
{
"code": 200,
"content": {
"status": "ok",
"action": "import",
"error_code": null,
"import_info": {
"successCount": 3,
"failCount": 0
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
{
"code": 200,
"content": {
"status": null,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限および共通リクエストエラーについては、共通エラー定義を参照してください。
タスクエラーは動的に返されます。failedItems の一致分岐で HTTP 400 となる場合の errorCode は error_code と等しくなります(ft.InternalServerError も 400 で返される場合があります)。その他の登録済み ft.* は対応するビジネスステータスを使用し、通常の >=500 は一律 ft.InternalServerError となります。実際の HTTP、errorCode およびエラー content.import_info に基づいて判断し、すべてのタスクエラーを単一のステータスに固定しないでください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答の説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータの使用、またはパラメータが規則に違反している | パラメータ解析失敗 | Query パラメータ表と例を確認してください。 |
| 406 | ft.ParameterValidationFailed | taskId が空 | パラメータ解析失敗 | 有効な元の taskId を入力してください。 |
| 403 | ft.Forbidden | タスクは存在するが、wksp_uuid または creator が現在の呼び出しと一致しない(ロングタスクの再作成で所有情報が欠落したキャッシュを含む) | 操作権限がありません | 元のワークスペースと元の Key のリソース ID を使用してください。ID が正しいにもかかわらず 403 が返る場合は、taskId を保持して管理者に期限切れ/タスクログの確認を依頼してください。他の管理 Key を借りてアクセスすることはできません。 |
| 400 | ft.JsonFormatError | 非同期タスクに fileContentError が記録されている | 一部の json ファイルの形式エラー | リソースパッケージ内の該当 JSON を修正し、インポート済みリソースを確認したうえで再アップロードしてください。 |
| 500 | ft.InternalServerError | タスクキャッシュ/キュー、ファイルシステム、データベース、または未処理のタスクステータス/JSON 処理の失敗 | 内部エラー | まず同一ワークスペース・同一 Key でタスクおよびリソースの現在の状態を照会し、キュー投入済み/部分保存済みかどうかを確認してから再試行してください。むやみにインポートや上書きを繰り返さないでください。 |