使用 API 可能需要很长时间才能完成

项目
04/08/2023

诸如复制或通过 URL 上传之类的方案有时可能无法在限定时间内完成。为了处理这些方案并保持 API 响应低延迟，使用长时间运行的操作模式实现这些操作。

应用请求通过 API 执行长时间运行的操作。 API 接受操作，并返回 202 Accepted 响应以及 API URL 的 Location 头，以便于检索操作状态报告。
应用请求获取操作状态报告 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"
}

使用 API 可能需要很长时间才能完成

初始操作请求

通过监视器 URL 检索状态报告

通过监视器 URL 检索已完成状态报告

检索已完成的操作的结果

其他资源