可续传上传

本页介绍了如何通过 REST 协议向 Google Photos Library API 发出可续传上传请求。当数据流因通信故障而中断后,您可以利用此协议恢复上传操作。

如果您是使用客户端库的开发者,请注意,某些客户端库为可续传上传提供原生支持。

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

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

出现网络故障时,可续传上传还可以减少带宽使用量,因为您不必从头开始重新上传大型文件。

第 1 步:启动上传会话

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

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 文件。 此示例使用初始化上传会话时在标头字段 x-goog-upload-chunk-granularity 中返回的分块大小为 262,144 字节。请注意,每次上传包含的字节都是 262144 的倍数。

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

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

然后,您可以使用此偏移量继续上传。您必须按照服务器提供的偏移量继续播放,除非您发送合并的上传和最终确定命令,在这种情况下,您也可以通过偏移量 0 恢复。

如果查询命令的 HTTP 响应中出现 X-Goog-Upload-Status 标头,但该值不是 active,则表示上传已终止。