执行可续传上传

本页面介绍了如何在 Cloud Storage JSON 和 XML API 中发出可续传上传请求。当数据流因通信故障而中断后，您可以利用此协议恢复上传操作。如需详细了解此功能及其使用时机，请参阅可续传上传。

启动可续传上传会话

如需启动可续传上传会话，请执行以下操作：

JSON API

创建一个针对 URI https://storage.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/o 的 POST 请求。
添加查询参数 uploadType=resumable。例如，对于名为 myBucket 的存储分区，请创建以下请求：
```
POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable
```
如果您没有文件的任何元数据，请添加 name 查询参数以确定与上传相关联的资源。例如，如需指定对象的名称为 myObject，请创建以下请求：
```
POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&name=myObject
```
如果您有文件的元数据，请以 JSON 格式向请求正文添加元数据，否则，请将请求正文留空。
添加以下 HTTP 标头：
- X-Upload-Content-Type。可选。设置为后续请求中传输的文件数据的 MIME 类型。如果未在元数据中或通过此标头指定数据的 MIME 类型，则系统会以 application/octet-stream 形式提供对象。
- X-Upload-Content-Length。可选。设置为后续请求中传输的文件数据的字节数。
- Content-Type。如果您有文件的元数据，则需要添加此标头。设置为 application/json; charset=UTF-8。
- Content-Length。除非您使用分块传输编码，否则需要添加此标头。设置为此初始请求正文中的字节数。
- Origin。如果您已启用跨源资源共享，则需要添加此标头。您还必须在后续上传请求中使用此标头。
发送请求。

示例

以下示例展示了如何使用名为 myBucket 的存储分区启动可续传会话。您可以从 OAuth 2.0 Playground 获取授权访问令牌。

POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable HTTP/1.1
  Authorization: Bearer [YOUR_AUTH_TOKEN]
  Content-Length: 38
  Content-Type: application/json; charset=UTF-8
  X-Upload-Content-Type: image/jpeg
  X-Upload-Content-Length: 2000000
  {
    "name": "myObject"
  }

下一部分将介绍如何处理响应。

XML API

如需开始执行可续传上传，请向 Cloud Storage 发送 POST Object 请求。POST Object 请求不包含您要上传的文件，而是包含若干标头，用于告知 Cloud Storage 系统您要执行可续传上传。具体而言，POST Object 请求必须具有以下内容：

空实体正文。
Content-Length 请求标头，该标头必须设置为 0。
x-goog-resumable 标头，该标头必须设置为 start。
在针对正在上传的文件的后续上传请求中使用的 Origin 标头（如果您已启用跨源资源共享）。

示例以下示例展示了如何为正在上传到 example 存储分区的 music.mp3 文件启动可续传上传。

    POST /music.mp3 HTTP/1.1
    Host: example.storage.googleapis.com
    Date: Fri, 01 Oct 2010 21:56:18 GMT
    Content-Length: 0
    Content-Type: audio/mpeg
    x-goog-resumable: start
    Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

保存可续传会话 URI

请复制并保存可续传会话 URI，以便在后续请求中使用。

JSON API

如果会话启动请求成功，则响应将包含 200 OK HTTP 状态代码。此外，它还包含一个 Location 标头，该标头指定可续传会话 URI。使用可续传会话 URI 上传文件数据并查询上传状态。

示例

以下示例展示了一个响应，其中包含一个名为 myBucket 的存储分区的可续传会话 URI：

HTTP/1.1 200 OK
  Location: https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2
  Content-Length: 0

XML API

使用 POST Object 请求启动可续传上传后，Cloud Storage 会返回 201 Created 状态消息。该状态消息包含 Location 标头，其值为可续传会话 URI。您必须保存该会话 URI，因为您将在上传操作期间的所有后续请求中使用它。

示例以下示例展示了对“启动可续传上传”部分所示 Post Object 请求的响应。

  HTTP/1.1 201 Created
  Location: https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 0
  Content-Type: audio/mpeg

上传文件

JSON API

借助以下两种方法，您可以使用可续传会话上传文件：

使用单一请求。此方法通常具有最佳的效果，因为它需要较少的请求，因此具有更好的性能。
使用多个数据块。在以下情况中，请使用此方法：
- 您需要减少任何单一请求中传输的数据量。如果有固定的单个请求时间限制（例如某些类别的 App Engine 请求），您可能就需要这样做。
- 您需要提供自定义指示，以显示上传进度。

单一请求

如需使用单一请求上传文件，请执行以下操作：

创建一个针对可续传会话 URI 的 PUT 请求。
将文件的数据添加到请求正文。
添加一个 Content-Length HTTP 标头，并将其设置为文件中的字节数。
发送请求。

如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。

如果请求成功，您会收到 200 OK 或 201 Created 响应，以及与资源相关联的任何元数据。

示例以下示例展示了一个可续传请求，该请求使用之前获得的可续传会话 URI 将整个 200 万字节的 JPEG 文件上传到 myBucket：

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg
Content-Range: bytes 0-1999999

多个数据块

如需使用多个数据块上传文件，请执行以下操作：

创建一个针对可续传会话 URI 的 PUT 请求。
将数据块的数据添加到请求正文。除了结束上传的最后一个数据块之外，数据块的大小应该是 256 KB（256 x 1024 字节）的整数倍。请尽量使用较大的数据块，以便高效上传。
添加以下 HTTP 标头：
- Content-Length。设置为当前数据块中的字节数。
- Content-Range：设置此标头可指明要上传文件中的哪些字节。例如，Content-Range: bytes 0-524287/2000000 表示您要上传某个 200 万字节文件中的前 524288 (256 x 1024 x 2) 个字节。
发送请求并处理响应。如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。
对文件中剩余的每个数据块重复执行第 1 步到第 4 步。使用响应中的 Range 标头来确定从何处开始上传下一个分块。请勿假定服务器已收到上一请求中发送的所有字节。

当整个文件上传完毕后，您会收到 200 OK 或 201 Created 响应，以及与资源相关联的任何元数据。

示例

以下示例展示了一个请求，该请求使用之前获得的可续传会话 URI 将文件的前 524288 字节 (512 KB) 发送到 myBucket：

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
      Content-Length: 524288
      Content-Type: image/jpeg
      Content-Range: bytes 0-524287/2000000

如果请求成功，则服务器会返回 308 Resume Incomplete，以及用于标识目前已存储字节总数的 Range 标头：

HTTP/1.1 308 Resume Incomplete
    Content-Length: 0
    Content-Range: bytes=0-524287

使用 Range 标头中返回的上限值来确定从何处开始上传下一个数据块。通过 PUT 继续放置文件的每个数据块，直到整个文件上传完毕。

当整个文件上传完毕后，您会收到 200 OK 或 201 Created 响应，以及与资源相关联的任何元数据。

XML API

实现一个将文件块发送到 Cloud Storage 的 PUT Object 请求。使用您获取的会话 URI 作为 PUT 请求的 URI。该请求还包含一个 Content-Length 标头，您必须使用该标头指定要上传的文件的大小。

此外，您必须在该请求中使用标准的 Cloud Storage 主机名 (storage.googleapis.com)，这一点与 POST Object 请求一样。您无需使用显式身份验证令牌，因为会话 URI 实际上就是身份验证令牌。

示例

以下示例展示了如何为已启动的“可续传上传”上传 music.mp3 文件：

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 7351375

如果 PUT Object 请求未中断且文件上传成功，则 Cloud Storage 会返回 200 OK 状态代码。如果上传中断，您可以恢复上传。

您应通过发送另一个 PUT Object 请求来查询服务器收到的字节数。PUT Object 请求必须具有以下内容：

空实体正文。
Content-Length 请求标头，该标头必须设置为 0。
Content-Range 请求标头，用于指定您要查询其状态的字节范围。
等同于可续传上传的会话 URI 的请求 URI。

Content-Range 请求标头的值必须采用以下格式：

Content-Range: bytes */<content-length>

其中 <content-length> 是您在原始 PUT Object 请求中指定的 Content-Length 标头的值。

此外，您必须在该请求中使用标准的 Cloud Storage 主机名 (storage.googleapis.com)。

以下示例展示了如何在可续传上传中断后查询 Cloud Storage 系统：

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 22:25:53 GMT
  Content-Range: bytes */7351375
  Content-Length: 0

恢复中断的上传

如果上传请求在收到响应之前终止，或者您收到 503 或 500 Service Unavailable 响应，则您需要恢复中断的上传。如需恢复中断的上传，请执行以下操作：

JSON API

如需查询上传状态，请创建一个针对可续传会话 URI 的空 PUT 请求。
添加一个 Content-Range 标头，用于表明文件中的当前位置未知。

例如，如果您的文件总长度为 200 万字节，请将 Content-Range 设为 */2000000。

如果您不知道文件的完整大小，请将 Content-Range 设为 */*。
发送请求。
处理响应。
- 200 OK 或 201 Created 响应表明上传已完成，无需执行进一步操作。
- 308 Resume Incomplete 响应表明您需要继续上传文件。
如果您收到了 308 Resume Incomplete 响应，请处理该响应的 Range 标头，该标头表明 Cloud Storage 目前已收到哪些字节。您将会在下一步中用到此数字。如果 Cloud Storage 尚未收到任何字节，则该响应没有 Range 标头。

例如，bytes=0-42 的 Range 标头表明已收到文件的前 43 个字节。
现在，您已知道从何处恢复上传，请通过发送剩余数据或下一个数据块来继续上传文件。请添加一个 Content-Range 标头，用于表明您要发送文件的哪一部分。

例如，Content-Range: bytes 43-1999999/2000000 表明您要发送 43 - 1999999 字节。

XML API

您可以通过发送 PUT Object 请求来恢复上传操作。PUT Object 请求必须具有以下内容：

包含仍需上传的字节范围的实体正文。您可以通过从 Content-Length 中减去（您之前获得的）Range 来确定此范围。
Content-Length 请求标头，用于指定您要在当前请求中上传的字节数。
Content-Range 请求标头，用于指定您要在请求中上传的字节范围。
等同于可续传上传的会话 URI 的请求 URI。

您必须在该请求中使用标准的 Cloud Storage 主机名 (storage.googleapis.com)。

示例

以下示例展示了一个 PUT Object 请求，该请求继续将 music.mp3 文件上传到示例存储分区中。

PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
Date: Fri, 01 Oct 2010 22:25:53 GMT
Content-Range: bytes 2359296-7351374/7351375
Content-Length: 4992079

您可以根据需要多次恢复上传，但在重试请求时，请使用截断指数退避算法。如需查看示例，请参阅此逻辑的 Boto 实现。

文件上传成功后，Cloud Storage 会返回 200 OK 状态代码。

详细了解可选优化措施

取消上传

如果您想取消上传并阻止对上传执行任何进一步操作，请针对唯一上传 URI 发出 DELETE 请求。DELETE 请求成功后，进一步尝试查询或恢复上传将导致 4xx 响应。

JSON API

示例

以下示例展示了如何取消可续传上传：

DELETE https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 0

XML API

示例

以下示例展示了如何取消可续传上传：

 DELETE https://example.storage.googleapis.com/myFile.zip?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
    Content-Length: 0

执行可续传上传

启动可续传上传会话

JSON API

XML API

保存可续传会话 URI

JSON API

XML API

上传文件

JSON API

单一请求

多个数据块

XML API

恢复中断的上传

JSON API

XML API

取消上传

JSON API

XML API

后续步骤