可续传上传

转到示例

本页面讨论 Cloud Storage 中的可续传上传。建议您使用可续传上传来上传大型文件,因为在上传过程中网络出现故障时,您不必从头开始重新上传。

简介

借助可续传上传,您可以在数据流因通信故障而中断后,恢复数据传输到 Cloud Storage 的操作。可续传上传的工作原理是发送多个请求,每个请求包含您正在上传的对象的一部分。这与简单上传不同,后者在单个请求中包含对象的所有数据,一旦中途失败,则必须从头开始重新上传。

  • 如果您要上传大型文件或通过较慢的连接上传,请使用可续传上传。如需了解使用可续传上传时的示例文件大小临界值,请参阅上传大小注意事项

  • 一次完成的可续传上传视为一项 A 类操作

工具和 API 如何使用可续传上传

根据您与 Cloud Storage 的交互方式,系统可能会代表您自动管理可续传上传。点击下表中的标签页可以了解详情:

控制台

Cloud Console 会代表您自动管理可续传上传。但是,如果您在上传过程中刷新或离开 Cloud Console,则系统会取消上传。

gsutil

借助 gsutil 命令行工具,您可以使用 boto 配置文件中的 resumable_threshold 参数设置执行可续传上传的最小大小。resumable_threshold 的默认值为 8 MiB。

客户端库

C++

您可以在 WriteObject 方法中切换使用可续传上传。

C#

您可以使用 CreateObjectUploader 启动可续传上传。

Go

您可以使用 Writer.ChunkSize 控制执行可续传上传的最小大小。Go 始终会执行分块可续传上传。

Java

可续传上传是通过 writer 方法控制的。

Node.js

使用 createWriteStream 方法时,系统会自动管理可续传上传。

PHP

系统会代表您自动管理可续传上传,但您可以使用 resumable 选项直接进行控制。

Python

如果文件大于 8 MiB,则系统会自动进行可续传上传。或者,您也可以使用 Resumable Media 自行管理可续传上传。

Ruby

所有上传都被视为可续传上传。

REST API

JSON API

Cloud Storage JSON API 使用包含查询参数 uploadType=resumablePOST Object 请求来启动可续传上传。此请求会返回一个会话 URI,您随后可以在一个或多个 PUT Object 请求中使用该 URI 上传对象数据。如需查看有关构建您自己的可续传上传逻辑的分步指南,请参阅执行可续传上传

XML API

Cloud Storage JSON API 使用包含查询参数 uploadType=resumablePOST Object 请求来启动可续传上传。此请求会返回一个会话 URI,您随后可以在一个或多个 PUT Object 请求中使用该 URI 上传对象数据。如需查看有关构建您自己的可续传上传逻辑的分步指南,请参阅执行可续传上传

未知规模的可续传上传

可续传上传机制支持传输事先不知道大小的文件。对于在上传过程中即时压缩对象等情况而言,这非常有用,因为在传输开始时很难预测压缩文件的确切大小。如果您希望进行可在中断后恢复的流式传输,或者如果分块传输编码不适用于您的应用,则该机制非常有用。

如需了解详情,请参阅流式传输

注意事项

如果您正在构建自己的客户端(用于直接将可续传上传请求发送到 JSON 或 XML API),此部分会非常有用。

会话 URI

启动可续传上传时,Cloud Storage 会返回一个会话 URI,您可以在后续请求中使用该 URI 上传实际数据。JSON API 中的会话 URI 示例如下:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

XML API 中的会话 URI 示例如下:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

此会话 URI 充当身份验证令牌,因此使用它的请求不需要签名,并且任何人都可以在不进行任何进一步的身份验证的情况下,使用这些请求将数据上传到目标存储分区。因此,请谨慎分享会话 URI,并且仅通过 HTTPS 分享。

会话 URI 的有效期为一周。如果您在请求中使用的会话 URI 过期,则会收到 404 Not Found 状态代码。在这种情况下,您必须启动新的可续传上传,获得新的会话 URI,然后使用新的会话 URI 从头开始上传。

上传性能

可续传上传固定在您启动上传操作的地区中。例如,如果您在美国启动可续传上传,并将会话 URI 提供给亚洲的客户端,则上传仍会经由美国进行。如果执行可续传上传的地区并非是启动上传操作的地区,可能会导致上传速度变慢。

如果您使用 Compute Engine 实例启动可续传上传,则该实例应与您上传到的 Cloud Storage 存储分区位于同一位置。然后,您可以使用地理位置 IP 服务来选择将客户请求路由到的 Compute Engine 地区,这有助于将流量局限到某个地理位置地区。

重试准则

  • 您应重试返回以下状态代码的任何请求:

    • 408 Request Timeout
    • 429 Too Many Requests
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • 没有其他 4XX 代码被视为可重试。请通过启动新的可续传上传来处理这些错误,包括 404 Not Found

  • 执行重试请求时,请使用截断指数退避算法

完整性检查

我们建议您请求对最终上传的对象进行完整性检查,以确保其与源文件相同。为此,您可以计算源文件的 MD5 digest,并将其添加到 Content-MD5 请求标头中。

如果您花了很长时间上传大型文件,检查上传文件的完整性尤其重要,这是因为上传操作过程中源文件被修改可能性会增加。

后续步骤