完了までに時間がかかる API を操作する
一部のシナリオでは、コピーやURL からのアップロードが一定時間内に完了できないことがあります。 こうしたシナリオに対処して、API の応答待機時間を短くするために、次に示すように、長時間実行のアクション パターンを使用したアクションが実装されています。
- アプリが API 経由で長時間実行のアクションを要求します。 API はアクションを承諾して、アクション ステータス レポートを取得するための API URL に関する Location ヘッダーとともに
202 Accepted応答を返します。 - アプリは、アクション ステータス レポート URL を要求して、長時間実行アクションの進行状況を含む AsyncJobStatus 応答を受け取ります。
- 長時間実行のアクションが完了します。 次回、アプリはアクション ステータス レポート URL を要求して、アクションの完了を含む AsyncJobStatus 応答を受け取ります。
最初のアクション要求
コピー シナリオの例を順を追って説明します。 このシナリオでは、アプリは大量のデータが格納されているフォルダーのコピーを要求します。 この要求は、データが大量であるため完了までに数秒間かかる可能性があります。
POST /drive/items/{folder-item-id}/copy
Content-Type: application/json
Prefer: respond-async
{
"parentReference": {
"path": "/drive/root:/Documents"
},
"name": "Copy of LargeFolder1"
}
API は、アクションが承諾されたことと、長時間実行アクションのステータスを取得するための URL を応答で返します。
HTTP/1.1 202 Accepted
Location: https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
多くの場合、コピー アクションはアプリが追加の作業をすることなく完了するため、これが要求の最後になります。 ただし、アプリでコピー アクションのステータスを表示する場合や、そのアクションがエラーなしで完了したことを確認する場合は、そうするためにモニター URL を使用できます。
モニター URL からステータス レポートを取得する
コピー アクションの状態を確認するために、アプリは前の応答で提供された URL に要求を行います。 注: この要求には、認証は必要ありません。この URL の有効期間は短く、最初の呼び出し元に一意であるためです。
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
サービスは、長時間実行のアクションがまだ進行中であるという情報を含む応答を返します。
HTTP/1.1 202 Accepted
Content-type: application/json
{
"operation": "ItemCopy",
"percentageComplete": 27.8,
"status": "inProgress"
}
この情報は、コピー アクションの進行状況に関する最新情報をユーザーに提供するために使用できます。 アプリは、ステータスの最新情報を要求してアクションの進行状況を追跡するために、モニター URL へのポーリングを継続できます。
モニター URL から完了状態レポートを取得する
コピー操作が完了してから数秒経過しています。 このときにアプリがモニター URL に要求を送信すると、完了したアクションの結果にリダイレクトする応答が返されます。
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
アクションが完了すると、モニター サービスからの応答で、結果の resourceId が返されます。
HTTP/1.1 303 See Other
Content-type: application/json
{
"percentageComplete": 100.0,
"resourceId": "01MOWKYVJML57KN2ANMBA3JZJS2MBGC7KM",
"status": "completed"
}