管理长时间运行的操作

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

每当您通过云端硬盘 API 或其客户端库对 files 资源调用 download() 方法以下载文件内容时，Google 云端硬盘 API 都会返回一个 LRO。

该方法会向客户端返回 operations 资源。您可以使用 operations 资源来异步检索 API 方法的状态，方法是通过 get() 方法轮询操作。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 类型，系统会使用默认 MIME 类型下载 Google Workspace 文档。如需了解详情，请参阅默认 MIME 类型。

• 可选。revision_id 查询参数是要下载的文件的修订版本 ID。只有在下载 blob 文件、Google 文档和 Google 表格时，才会显示此选项。下载不受支持的文件的特定修订版时，返回错误代码 INVALID_ARGUMENT。

download() 方法是下载 MP4 格式 Vids 文件的唯一方法，通常最适合下载大多数视频文件。

为 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。

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

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

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

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() 请求的响应中返回。由于云端硬盘 API 不支持 List() 方法，因此无法通过其他方式检索该值。如果 name 值丢失，您必须再次调用 download() 方法请求来生成新响应。

get() 请求的响应包含一个表示长时间运行的操作的资源。如需了解详情，请参阅下载响应。

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

下载修订版本

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

如需下载 blob 文件的修订内容，您必须对 revisions 资源调用 get() 方法，并提供要下载的文件的 ID、修订的 ID 和 alt=media 网址参数。alt=media 网址参数会告知服务器，请求以其他响应格式下载内容。

您无法使用 get() 方法和 alt=media 网址下载 Google 文档、表格、幻灯片和视频的修订版本。否则，它会生成 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 错误代码。

下表说明了每个代码的原因，并提供了相应的处理建议。对于许多错误，建议采取的措施是使用指数退避算法再次尝试请求。

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

相关主题

• 下载和导出文件
• 管理文件修订版本