执行可续传上传

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

启动可续传上传会话

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

JSON API

  1. 创建一个针对 URI https://storage.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/oPOST 请求。
  2. 添加查询参数 uploadType=resumable。例如,对于名为 myBucket 的存储分区,请创建以下请求:

    POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable
  3. 如果您没有文件的任何元数据,请添加 name 查询参数以确定与上传相关联的资源。例如,如需指定对象的名称为 myObject,请创建以下请求:

    POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&name=myObject
  4. 如果您有文件的元数据,请以 JSON 格式向请求正文添加元数据,否则,请将请求正文留空。

  5. 添加以下 HTTP 标头:

    • X-Upload-Content-Type。可选。设置为后续请求中传输的文件数据的 MIME 类型。如果未在元数据中或通过此标头指定数据的 MIME 类型,则系统会以 application/octet-stream 形式提供对象。
    • X-Upload-Content-Length。可选。设置为后续请求中传输的文件数据的字节数。
    • Content-Type。如果您有文件的元数据,则需要添加此标头。设置为 application/json; charset=UTF-8
    • Content-Length。除非您使用分块传输编码,否则需要添加此标头。设置为此初始请求正文中的字节数。
    • Origin。如果您已启用跨源资源共享,则需要添加此标头。您还必须在后续上传请求中使用此标头。
  6. 发送请求。

示例

以下示例展示了如何使用名为 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 请求),您可能就需要这样做。
    • 您需要提供自定义指示,以显示上传进度。

单一请求

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

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

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

如果请求成功,您会收到 200 OK201 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

多个数据块

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

  1. 创建一个针对可续传会话 URI 的 PUT 请求。
  2. 将数据块的数据添加到请求正文。除了结束上传的最后一个数据块之外,数据块的大小应该是 256 KB(256 x 1024 字节)的整数倍。请尽量使用较大的数据块,以便高效上传。
  3. 添加以下 HTTP 标头:
    • Content-Length。设置为当前数据块中的字节数。
    • Content-Range:设置此标头可指明要上传文件中的哪些字节。例如,Content-Range: bytes 0-524287/2000000 表示您要上传某个 200 万字节文件中的前 524288 (256 x 1024 x 2) 个字节。
  4. 发送请求并处理响应。如果上传请求中断或者您收到 5xx 响应,请按照恢复中断的上传中的步骤操作。

  5. 对文件中剩余的每个数据块重复执行第 1 步到第 4 步。使用响应中的 Range 标头来确定从何处开始上传下一个分块。请勿假定服务器已收到上一请求中发送的所有字节。

当整个文件上传完毕后,您会收到 200 OK201 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 OK201 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>

其中 &lt;content-length&gt; 是您在原始 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
  

恢复中断的上传

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

JSON API

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

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

    如果您不知道文件的完整大小,请将 Content-Range 设为 */*

  3. 发送请求。

  4. 处理响应。

    • 200 OK201 Created 响应表明上传已完成,无需执行进一步操作。
    • 308 Resume Incomplete 响应表明您需要继续上传文件。
  5. 如果您收到了 308 Resume Incomplete 响应,请处理该响应的 Range 标头,该标头表明 Cloud Storage 目前已收到哪些字节。您将会在下一步中用到此数字。如果 Cloud Storage 尚未收到任何字节,则该响应没有 Range 标头。

    例如,bytes=0-42Range 标头表明已收到文件的前 43 个字节。

  6. 现在,您已知道从何处恢复上传,请通过发送剩余数据或下一个数据块来继续上传文件。请添加一个 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

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

示例

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

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

后续步骤