可续传上传

本页介绍了如何通过 REST 协议向 Google 相册库 API 发送断点续传上传请求。使用此协议可以恢复上传操作 因为通信故障会中断数据流。

在以下情况下,请使用可续传上传选项:

  • 您正在上传大型文件。
  • 出现网络中断或某些其他传输故障的可能性为 高(例如,当您从移动应用上传文件时)。

出现网络故障时,断点续传还可减少带宽占用,这是因为您无需从头开始重新上传大型文件。

第 1 步:启动上传会话

将 POST 请求发送到 ,以启动可续传上传会话 https://photoslibrary.googleapis.com/v1/uploads。使用可续传上传 此请求中返回的网址,请上传文件。

POST 请求必须包含以下标头:

标头字段
Content-Length 请求正文为空,因此设置为 0
X-Goog-Upload-Command 设为 start
X-Goog-Upload-Content-Type 设置为文件的 MIME 类型,例如 image/jpeg
X-Goog-Upload-Protocol 设为 resumable
X-Goog-Upload-Raw-Size 将此项设为要导入的文件数据的总字节数 已转移。

以下是 POST 请求标头:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

第 2 步:保存会话网址

如果请求成功,POST 请求将返回 200 OK HTTP 状态代码,包括 以下标头。

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

标头字段 x-goog-upload-chunk-granularity 包含字节对齐 和大小粒度。如果上传文件 分成多个数据块进行上传时,除了最后一次上传数据以外,所有上传数据 必须是此值的倍数。也就是说,该文件的上传字节 必须与此值对齐。在最后一个数据块中,您可以上传剩余的数据块 字节。

标头字段 X-Goog-Upload-URL 包含一个唯一网址, 完成上传。复制并保存 可续传会话网址,以便在后续请求中使用。

第 3 步:上传文件

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

  1. 使用单一请求。这通常是最佳方法 因为它需要的请求较少,因此具有更好的性能。
  2. 使用多个数据块。在这种方法中,上传 处理多个请求。数据分块 x-goog-upload-chunk-granularity 的倍数。如有必要, 可以重试分块请求

    在以下情况中,请使用此方法:

    • 您需要减少任意单个订单项中传输的数据量 请求。在有固定的时间限制的情况下,您可能需要这样做 。
    • 您需要提供显示上传内容的自定义指示器 进度。
    • 您需要知道何时可以放心地舍弃数据。

单一请求

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

  1. 创建针对可续传会话网址的 POST 请求。
  2. 将文件的数据添加到请求正文。
  3. 添加以下 HTTP 标头:

    • Content-Length:设置为 文件。
    • X-Goog-Upload-Command:设置为 upload, finalize
  4. 发送请求。

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

如果请求成功,您会收到 200 OK HTTP 状态 和上传令牌。 您可以使用此上传令牌创建媒体内容

多个数据块

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

  1. 创建针对可续传会话网址的 POST 请求。
  2. 将分块的数据添加到请求正文。

    除了完成上传的最后一个数据块之外,请创建 是可接受分块大小的倍数的其他数据块。将 上传尽可能大的数据块,以便高效上传。

  3. 添加以下 HTTP 标头:

    • Content-Length:设置为 数据块。
    • X-Goog-Upload-Command:设置为 upload。 对于最后一个数据块,请设置为 upload, finalize
    • X-Goog-Upload-Offset:设置为应写入字节的偏移量。请注意,您必须上传字节 连续调用。第一个偏移量为 0
  4. 发送请求。

    如果上传请求被中断或您收到 5xx 请按照恢复 上传中断

  5. 对文件中剩余的每个数据块重复上述步骤。

如果请求成功,您会收到 200 OK HTTP 状态 代码和上传令牌。 创建 媒体内容

示例

单一请求

以下示例展示了上传 3,039,417 字节的 JPEG 文件。

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

响应包含上传网址和预计数据块大小:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

最终的上传请求:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

多个数据块

以下示例展示了上传 多个分块中的 3,039,417 字节 JPEG 文件,使用可续传会话 网址和上一步中获取的可接受的数据块大小粒度。 本示例使用的区块大小为 262,144 个字节,在 标头字段 x-goog-upload-chunk-granularity,当 上传会话已初始化。请注意,每次上传的数据中均包含 262,144 的倍数字节。

初始化上传会话以接收上传网址和分块大小 如上一步中所述:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

响应中包含上传网址和预期的数据块大小:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

第一个数据块:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

第二个数据块:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

最后一个数据块:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

恢复中断的上传

上传请求中断或您收到非 200 HTTP 状态 代码,查询服务器以了解上传成功率。

以下是对可续传会话网址的 POST 请求。X-Goog-Upload-Command 应设置为 query

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

服务器的响应包含 200 OK HTTP 状态代码和 当前上传文件的大小。

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

然后,您可以使用该偏移量继续上传。您必须在偏移值处继续播放 (除非您发送“upload”和“finalize”组合命令),否则 在这种情况下,也可以在偏移 0 处恢复播放。

如果查询命令的 HTTP 响应中的 X-Goog-Upload-Status 标头 存在且值不是 active,则表示上传 已经被终止。