管理长时间运行的操作

长时间运行的操作 (LRO) 是一种 API 方法，其完成时间比 API 响应的适当时间要长。通常，您不希望在任务运行时保持调用线程处于打开状态，因为这会带来糟糕的用户体验。相反，最好向用户返回某种类型的承诺，并允许他们稍后回来查看。

每次您对 files 资源调用 download 方法以通过 Drive API 或其 客户端 库下载文件内容时，Google Drive API 都会返回 LRO。

该方法会向客户端返回 operations 资源， 。您可以使用 operations 资源通过 get 方法轮询操作，以异步检索 API 方法的状态。Drive API 中的 LRO 遵循 Google Cloud LRO 设计 模式。

如需了解详情，请参阅长时间运行的操作。

流程概览

下图展示了 file.download 方法的工作原理的简要步骤。

1. 调用 files.download：当您的应用调用 download 方法时，它 会启动文件的 Drive API 下载请求。如需了解更多 信息，请参阅下载文件。

2. 请求权限：该请求会将身份验证凭据发送到 Drive API。如果您的应用需要使用尚未授予的用户身份验证来调用 Drive API，则会提示用户登录。您的应用还会请求使用 您在设置身份验证时指定的范围进行访问。

3. 开始下载：系统会发出 Drive API 请求以开始下载文件 。该请求可以发送到 Google Vids 或其他 Google Workspace 内容。

4. 启动 LRO：长时间运行的操作开始，并管理下载 过程。

5. 返回待处理的操作：Drive API 会返回一个待处理的 操作，其中包含有关发出请求的用户的信息以及 多个文件元数据字段。

6. 初始待处理状态：您的应用会收到待处理的操作以及 done=null的初始待处理状态。这表示文件尚未准备好下载，并且操作状态为待处理。

7. 调用 operations.get 并验证结果：您的应用会按 建议的时间间隔调用 get，以轮询操作结果并获取长时间运行的操作的最新状态 。如果返回 done=false 的待处理状态，您的应用必须继续轮询，直到操作返回完成状态 (done=true)。对于大型文件，预计需要轮询多次。如需了解详情，请参阅获取长时间运行的 操作的详细信息。

8. 检查待处理状态：如果从 LRO 返回 done=true 的待处理状态，则表示文件已准备好下载，并且操作状态已完成。

9. 返回包含下载 URI 的已完成操作：LRO 完成后， Drive API 会返回下载 URI，用户现在可以使用该文件。

下载文件

如需下载长时间运行的操作下的内容，请对 files资源使用download方法。该方法采用 file_id、mime_type 和 revision_id 参数：

• 必需。file_id 路径参数是要下载的文件的 ID。

• 可选。mime_type 查询参数表示该方法应使用的 MIME 类型。它仅在下载非 Blob 媒体内容（例如 Google Workspace 文档）时可用。如需查看受支持的 MIME 类型的完整列表，请参阅 Google Workspace 文档的导出 MIME 类型。

  如果未设置 MIME 类型，则 Google Workspace 文档将使用默认 MIME 类型下载。如需了解详情，请参阅默认 MIME 类型。

• 可选。revision_id 查询参数是要下载的文件的修订版本 ID。它仅在下载 Blob 文件、Google 文档和 Google 表格时可用。如果下载不受支持的文件上的特定修订版本，则返回错误代码 INVALID_ARGUMENT。

download 方法是下载 MP4 格式的 Vids 文件的唯一方法，通常最适合下载大多数视频文件。如果您尝试导出 Google Vids 文件，则会收到 fileNotExportable 错误。

为 Google 文档或表格生成的下载链接最初会返回重定向。点击新链接即可下载文件。

启动 LRO 的 download 方法的请求，以及提取最终下载 URI 的请求，都应使用资源密钥。如需了解详情，请参阅 使用资源密钥访问通过链接共享的云端硬盘文件。

此处显示了请求协议。

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

将 FILE_ID 替换为您要 下载的文件的 fileId。

默认 MIME 类型

如果下载非 Blob 内容时未设置 MIME 类型，系统会分配以下默认 MIME 类型：

下载响应

调用 download 方法时， 响应正文 由 表示长时间运行的操作的资源组成。该方法通常会返回一个链接，用于下载文件内容。

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

此输出包括以下值：

• RESOURCE_KEY：资源密钥有助于保护您的文件免遭 意外访问。如需了解详情，请参阅使用资源密钥访问通过链接共享的 云端硬盘文件 。

• NAME：服务器分配的名称。

• DOWNLOAD_URI：文件的最终下载 URI。

请注意，partialDownloadAllowed 字段表示是否允许 部分下载，并且在下载 Blob 文件内容时为 true 下载 Blob 文件内容时为。

获取长时间运行的操作的详细信息

长时间运行的操作是可能需要大量时间才能完成的方法调用。通常，新创建的下载操作最初会以待处理状态 (done=null) 返回，尤其是对于 Vids 文件。

您可以使用 operations 资源，通过添加服务器分配的唯一名称来检查正在处理的 LRO 的状态。

The get 方法会异步获取长时间运行的 操作的最新状态。客户端可以使用此方法，按 API 服务建议的时间间隔来轮询操作结果。

轮询长时间运行的操作

如需轮询可用的 LRO，请反复调用 get 方法，直到操作完成。 在每个 轮询请求之间使用指数退避算法，例如 10 秒。

LRO 的可用时间至少为 12 小时，但在某些情况下可能会持续更长时间。此持续时间可能会发生变化，并且不同文件类型之间可能会有所不同。资源过期后，需要发出新的 download 方法请求。

对 get 的任何请求都应使用资源密钥。如需了解详情，请参阅 使用资源密钥访问通过链接共享的云端硬盘文件。

此处显示了请求协议。

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

请注意，name 仅在对 download 请求的响应中返回。 没有其他方法可以检索它，因为 Drive API 不支持 list 方法。如果 name 值丢失，您必须通过再次调用 download 方法请求来生成新的响应。

对 get 请求的响应由表示长时间运行的操作的资源组成。如需了解详情，请参阅下载 响应。

当响应包含完成状态 (done=true) 时，长时间运行的操作已完成。

下载修订版本

您可以使用 headRevisionId字段 从 files 资源下载最新 修订版本。这会提取与您之前检索的文件元数据对应的修订版本。如需下载仍存储在云端的文件的所有先前修订版本的数据，您可以对 revisions 资源调用 list 方法，并使用 fileId 参数。这会返回文件中的所有 revisionIds。

如需下载 Blob 文件的修订版本内容，您必须对 revisions资源调用get方法，并使用要下载的文件的 ID、修订版本的 ID 和 alt=media 网址参数。alt=media 网址参数会告知服务器，系统正在请求内容下载作为替代响应格式。

无法使用带有 alt=media 网址的 get 方法下载 Google 文档、表格、幻灯片和 Vids 的修订版本。否则，系统会生成 fileNotDownloadable 错误。

alt=media 网址参数是一个 系统 参数，适用于 所有 Google REST API。如果您使用 Drive API 的客户端库，则无需明确设置此参数。

此处显示了请求协议。

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

替换以下内容：

• FILE_ID：您要 下载的文件的 fileId。
• REVISION_ID：您要下载的修订版本的 revisionId。

Google 文档、绘图和幻灯片修订版本会自动递增修订版本号。但是，如果删除了修订版本，则数字序列可能会出现间断，因此您不应依赖连续的数字来检索修订版本。

排查 LRO 问题

当 LRO 失败时，其响应会包含规范的 Google Cloud 错误 代码。

下表显示了每个错误代码、映射的 HTTP 状态代码、说明以及有关如何处理错误代码的建议。对于许多 错误，建议的操作是使用指数 退避算法再次尝试请求。

如需详细了解该错误模型及其使用方法，请参阅 API 设计指南。

相关主题

• 下载和导出文件