本页面介绍如何通过 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 步:上传文件
借助以下两种方法,您可以使用可续传会话上传文件:
- 使用单一请求。此方法通常是最佳方法,因为它需要的请求更少,因此性能更好。
-
使用多个数据块。在此方法中,通过将数据分块,在多个请求中进行上传。系统会以
x-goog-upload-chunk-granularity
的倍数将数据分块。如有必要,可以重试分块请求。在以下情况中,请使用此方法:
- 您需要减少任何单个请求中传输的数据量。当单个请求有固定的时间限制时,您可能需要执行此操作。
- 您需要提供自定义指示器来显示上传进度。
- 您需要知道何时可以安全地舍弃数据。
单一请求
如需使用单一请求上传文件,请执行以下操作:
- 创建对可续传会话网址的
POST
请求。 - 将文件的数据添加到请求正文。
添加以下 HTTP 标头:
Content-Length
:设置为文件中的字节数。X-Goog-Upload-Command
:设置为upload, finalize
。
发送请求。
如果上传请求中断或您收到 5xx
响应,请按照恢复中断的上传中的步骤操作。
如果请求成功,您会在响应正文中收到 200 OK
HTTP 状态代码和上传令牌。您可以使用此上传令牌创建媒体内容。
多个块
如需使用多个数据块上传文件,请执行以下操作:
- 创建对可续传会话网址的
POST
请求。 -
将分块的数据添加到请求正文。
除了完成上传的最后一个分块之外,请以可接受的分块大小的倍数创建其他分块。请尽量使用较大的数据块,以便高效上传。
-
添加以下 HTTP 标头:
Content-Length
:设置为分块中的字节数。X-Goog-Upload-Command
:设置为upload
。 对于最后一个数据块,设置为upload, finalize
。X-Goog-Upload-Offset
:设置为应写入字节的偏移量。请注意,字节必须连续上传。第一个偏移量为0
。
- 发送请求。
如果上传请求中断或您收到
5xx
响应,请按照恢复中断的上传中的步骤操作。 - 对文件中剩余的每个数据块重复上述步骤。
如果请求成功,您会在响应正文中收到 200 OK
HTTP 状态代码和上传令牌。您可以使用此上传令牌创建媒体内容。
示例
单一请求
以下示例展示了一个可续传请求,该请求会在单个请求中上传 3039417 字节的 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
中返回的分块大小为 262144 字节。请注意,每次上传包含的字节均为 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
,则表示上传已终止。