Creator の実行時間の長い操作 API V2

  • [アーティクル]

Azure Maps の一部の API では、非同期の要求-応答パターンが使用されます。 このパターンにより、Azure Maps で高可用性と応答性の高いサービスを提供できます。 この記事では、実行時間の長い非同期バックグラウンド処理の Azure Map 固有の実装について説明します。

要求を送信する

クライアント アプリケーションでは、HTTP API への同期呼び出しを使用して、実行時間の長い操作を開始します。 通常、この呼び出しは HTTP POST 要求の形式です。 非同期ワークロードが正常に作成された場合は、API によって、要求が受け入れられたことを示す HTTP 202 状態コードが返されます。 この応答には、実行時間の長い操作の状態を確認するためにクライアントがポーリングできるエンドポイントを指す Location ヘッダーが含まれています。

成功応答の例

Status: 202 Accepted
Operation-Location: https://atlas.microsoft.com/service/operations/{operationId}

呼び出しが検証に合格しなかった場合は、API によって、無効な要求に対する HTTP 400 応答が返されます。 応答本文は、要求が無効であった理由に関するより詳細な情報をクライアントに提供します。

操作の状態の監視

受け付けられた応答ヘッダーで提供される場所エンドポイントをポーリングして、実行時間の長い操作の状態を確認できます。 操作状態要求からの応答本文には、常に status プロパティと created プロパティが含まれています。 status プロパティでは、実行時間の長い操作の現在の状態が示されます。 返される可能性のある状態は、"NotStarted"、"Running"、"Succeeded"、"Failed" です。 created プロパティでは、実行時間の長い操作を開始する最初の要求が行われた時刻が示されます。 状態が "NotStarted" または "Running" のどちらかである場合は、応答で Retry-After ヘッダーも提供されます。 Retry-After ヘッダー (秒単位) を使用して、操作状態 API に対する次のポーリング呼び出しを行うタイミングを決定できます。

状態応答の実行の例

Status: 200 OK
Retry-After: 30
{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Running"
}

操作の完了の処理

実行時間の長い操作が完了すると、応答の状態は "Succeeded" または "Failed" のどちらかになります。 すべての応答で HTTP 200 OK コードが返されます。 実行時間の長い操作から新しいリソースが作成された場合、応答には、そのリソースに関するメタデータを指す Resource-Location ヘッダーも含まれています。 エラーが発生した場合、応答の本文には error プロパティが含まれています。 エラー データは、OData エラー仕様に準拠しています。

成功応答の例

Status: 200 OK
Resource-Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
 {
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "2021-05-06T07:55:19.5256829+00:00",
    "status": "Succeeded"
}

失敗応答の例

Status: 200 OK

{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Failed",
    "error": {
        "code": "InvalidFeature",
        "message": "The provided feature is invalid.",
        "details": {
            "code": "NoGeometry",
            "message": "No geometry was provided with the feature."
        }
    }
}