実行時間の長い操作

実行時間の長い操作 (LRO) は、応答性とスケーラビリティを維持しながら非同期ポーリングを可能にする非同期の時間のかかるタスクです。ポーリングとは、操作が完了するまで操作の状態を定期的に確認するために必要なクライアントパターンを指します。

Web サービスと API のコンテキストでは、LRO は実行にかなりの時間が必要なタスクまたはプロセスを指し、1 回の要求/応答サイクル内の即時完了には適切でなかっています。

このような操作の例としては、大規模なデータのアップロード、複雑な計算、バッチ処理、クラウド環境でのリソースプロビジョニングなどがあります。実行時間の長いすべての操作で Fabric が発生するわけではありません。一部の操作は、結果 URL を指定せずに完了まで実行されます。

API 仕様

LRO インフラストラクチャを使用する API は、次の 2 つの成功した結果のいずれかを返します。

HTTP 状態コード 200 OK または 201 CREATED - 結果が存在する場合、応答本文には API の結果が含まれます。
HTTP 状態コード 202 Accepted - 応答本文が空です。

LRO インフラストラクチャでは、次の 3 つの応答ヘッダーが自動的に追加されます。

Location header: 操作の状態をポーリングするための URL が含まれています。
x-ms-operation-id header: 操作の状態 URL を構築するために使用できる操作 ID が含まれています。
Retry-After header: 呼び出し元が操作の状態を照会する前に待機する秒数を表す整数が含まれます。

状態のポーリングと結果の取得

状態をポーリングし、操作の完了後に結果を取得するには、次の 2 つの方法があります。

場所ヘッダーを使用する: 操作の実行中に返される場所ヘッダーは、実行中の操作の操作 ID を持つ Get Operation State API です。操作の実行が完了すると、返される場所ヘッダーは、操作 ID と結果を含む Get Operation Result API です。
x-ms-operation-idを使用する: 最初の呼び出しの応答で返される x-ms-operation-id ヘッダーを使用して、操作ヘッダーで返される API 呼び出しをビルドできます。操作 ID を使用して Get Operation State API を使用して状態をプルし、(操作 ID を使用して) Get Operation Result API で結果を取得します。

操作の状態をポーリングするための C# コードサンプル

// Get operationUrl from ___location header or by building it with operation ID and Get State API.  
do 
{ 
  Thread.Sleep(retryAfter * 1000); // Get retryAfter value from Retry-After header. 
  response = client.GetAsync(operationUrl).Result;  
  jsonOperation = response.Content.ReadAsStringAsync().Result; 
  operation = JsonSerializer.Deserialize<FabricOperation>(jsonOperation); 
} while (operation.status != "Succeeded" && operation.status != "Failed");

項目の作成の例

これは、LRO 操作の例です。この例では、ユーザーは 2 つのノートブックを作成しました。

ステージ 1: 2 つのノートブックを作成する

2 つのノートブックを作成します。

ステージ 2: ノートブックをポーリングする

Get Operation State を使用して、ノートブックの作成をポーリングします。

Notebook 1 - 201 を返します。操作が完了しました。

{ 
  "id": "551e6a4d-d81a-4079-b08c-25cec3cebba9", 
  "type": "Notebook", 
  "displayName": "Notebook1", 
  "description": "", 
  "workspaceId": "a91e61ef-862e-4611-9d09-9c7cc07b2519" 
}

Notebook 2 - 202 を返します。操作が完了していません。ノートブック 2 は作成されません。

{ 
"status": "Running", 
"createdTimeUtc": "2023-11-13T22:24:40.477Z", 
"lastUpdatedTimeUtc": "2023-11-13T22:24:41.532Z", 
"percentComplete": 25 
}

ステージ 3: Notebook 2 をポーリングする

20 分待ってから、Get Operation State を使用して Notebook 2 をポーリングします。

GET https://api.fabric.microsoft.com/v1/operations/b80e135a-adca-42e7-aaf0-59849af2ed78

Notebook 2 - 201 を返します。操作が完了しました。ノートブック 2 が作成されます。

操作が完了しました - 200-OK http 状態コードを取得しました。応答本文は次のとおりです。

{ 
  "status": "Succeeded", 
  "createdTimeUtc": "2023-11-13T22:25:06.1193103", 
  "lastUpdatedTimeUtc": "2023-11-13T22:25:09.0255787", 
  "percentComplete": 100, 
  "error": null 
}

ステージ 4: ノートブック 2 の操作結果を取得する

Get Operation Result を使用して、Notebook 2 の操作結果を取得します。

GET https://api.fabric.microsoft.com/v1/operations/b80e135a-adca-42e7-aaf0-59849af2ed78/result

Notebook 2 - 200 を返します。ノートブック 2 が作成されます。

{ 
"id": "221a6eea-0f27-41eb-bcc5-e4d7b216ed43", 
"type": "Notebook", 
"displayName": " Notebook2", 
"description": "", 
"workspaceId": "a91e61ef-862e-4611-9d09-9c7cc07b2519" 
}

Last updated on 2025-03-27