本页介绍了如何通过 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 步:上传文件
借助以下两种方法,您可以使用可续传会话上传文件:
- 使用单一请求。这通常是最佳方法 因为它需要的请求较少,因此具有更好的性能。
-
使用多个数据块。在这种方法中,上传 处理多个请求。数据分块
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 状态
代码和上传令牌。
创建
媒体内容。
示例
单一请求
以下示例展示了上传 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
,则表示上传
已经被终止。