コンテンツにスキップ

ワークスペースリソースタスクステータスの照会



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 でタスクおよびリソースの現在の状態を照会し、キュー投入済み/部分保存済みかどうかを確認してから再試行してください。むやみにインポートや上書きを繰り返さないでください。

フィードバック

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