長時間実行アクションの処理 (ベータ版)Working with long running actions (beta)

一部の API 応答では、完了までに要する時間が不明です。Some API responses require indeterminate time to complete. アクションが完了するまで待機してから応答を返す代わりに、Microsoft Graph では長時間実行アクションのパターンを使用できます。Instead of waiting until the action is complete before returning a response, Microsoft Graph may use a long running actions pattern. このパターンを使用すると、アプリは、アクションの完了を待機する要求を行わずに、長時間実行されているアクションのステータス更新をポーリングすることができます。This pattern provides your app a way to poll for status updates on a long running action, without any request waiting for the action to complete.

一般的なパターンでは、以下の手順を実行します。The general pattern follows these steps:

  1. アプリが API 経由で長時間実行アクションを要求します。Your app requests a long running action via the API. API はアクションを承諾し、API URL の Location ヘッダーと共に 202 Accepted 応答を返して、アクションの状態レポートを取得します。The API accepts the action and returns a 202 Accepted response along with a Location header for the API URL to retrieve action status reports.
  2. アプリは、アクションの状態レポート URL を要求して、長時間実行アクションの進行状況を含む AsyncJobStatus 応答を受け取ります。Your app requests the action status report URL and receives an AsyncJobStatus response with the progress of the long running action.
  3. 長時間実行アクションが完了します。The long running action completes.
  4. アプリはアクションの状態レポート URL を再度要求して、アクションの完了を示す AsyncJobStatus 応答を受け取ります。Your app requests the action status report URL again and receives an AsyncJobStatus response showing the completion of the action.

最初のアクション要求Initial action request

DriveItem コピー シナリオの例を順を追って説明します。Let's walk through the steps for an example DriveItem Copy scenario. このシナリオでは、アプリは大量のデータが格納されているフォルダーのコピーを要求します。In this scenario, your app requests to copy a folder that contains a large amount of data. この要求は、データが大量であるため完了までに数秒間かかる可能性があります。This request will likely take several seconds to complete since the amount of data is large.

POST https://graph.microsoft.com/beta/me/drive/items/{folder-item-id}/copy
Content-Type: application/json

{
  "parentReference": {
    "path": "/drive/root:/Documents"
  },
  "name": "Copy of LargeFolder1"
}

API は、アクションが承諾されたことと、長時間実行アクションの状態を取得するための URL を応答で返します。The API responds that the action was accepted and the URL for retrieving the status of the long running action.

HTTP/1.1 202 Accepted
Location: https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

注: 場所の URL が返されても、Microsoft Graph API エンドポイントにあるとは限りません。Note: The location URL returned may not be on the Microsoft Graph API endpoint.

多くの場合、コピー アクションはアプリが追加の作業をすることなく完了するため、これが要求の最後になります。In many cases this may be the end of the request, since the copy action will complete without the app doing any additional work. ただし、アプリでコピー アクションの状態を表示することが必要な場合や、そのアクションがエラーなしで完了したことを確認する場合は、モニター URL を使用できます。However, if your app needs to show the status of the copy action or ensure that it completes without error, it can do so using the monitor URL.

モニター URL から状態レポートを取得するRetrieve a status report from the monitor URL

コピー アクションのステータスを確認するために、アプリは前の応答で提供された URL に要求を送信します。 注: この要求には、認証は必要ありません。この URL の有効期間は短く、最初の呼び出し元に一意であるためです。To check on the status of the copy action, the app makes a request to the URL provided in the previous response. Note: This request does not require authentication, since the URL is short-lived and unique to the original caller.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

サービスは、長時間実行のアクションがまだ進行中であるという情報を含む応答を返します。The service responses with information that the long running action is still in progress:

HTTP/1.1 202 Accepted
Content-type: application/json

{
  "operation": "ItemCopy",
  "percentageComplete": 27.8,
  "status": "inProgress"
}

この情報は、コピー アクションの進行状況に関する最新情報をユーザーに提供するために使用できます。 アプリは、ステータスの最新情報を要求してアクションの進行状況を追跡するために、モニター URL へのポーリングを継続できます。This information can be used to provide an update to the user about the progress of the copy action. The app can continue to poll the monitor URL to request status updates and keep track of the progress of the action.

モニター URL から完了状態レポートを取得するRetrieve a completed status report from the monitor URL

コピー操作が完了してから数秒経過しています。 このときにアプリがモニター URL に要求を送信すると、完了したアクションの結果にリダイレクトする応答が返されます。After a few seconds the copy operation has completed. This time when the app makes a request to the monitor URL the response is a redirection to the finished result of the action.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

アクションが完了すると、モニター サービスからの応答で、結果の resourceId が返されます。When the action has completed, the response from the monitor service will return the resourceId for the results.

HTTP/1.1 202 Accepted
Content-type: application/json

{
    "percentageComplete": 100.0,
    "resourceId": "01MOWKYVJML57KN2ANMBA3JZJS2MBGC7KM",
    "status": "completed"
}

完了した操作の結果を取得するRetrieve the results of the completed operation

ジョブが完了すると、モニター URL が結果の resourceId を返します。ここでは、元のアイテムの新しいコピーを返します。Once the job has completed, the monitor URL returns the resourceId of the result, in this case the new copy of the original item. resourceId を使用してこの新しいアイテムに対処することができます。次に例を示します。You can address this new item using the resourceId, for example:

GET https://graph.microsoft.com/beta/me/drive/items/{item-id}
HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "",
    "name": "Copy of LargeFolder1",
    "folder": { },
    "size": 12019
}

サポートされているリソースSupported resources

長時間実行アクションは、次の API メソッドでサポートされています。Long running actions are supported on the following API methods

リソースResource APIAPI
DriveItemDriveItem コピーCopy

前提条件Prerequisites

長時間実行アクションの実行に必要なアクセス許可と同じアクセス許可は、長時間実行アクションの状態をクエリするときにも必要です。The same permissions that are required to perform a long running action are also required to query the status of a long running action.