本页面介绍了如何向 Google Photos Library API 发出可续传上传请求 使用 REST 协议使用此协议可以恢复上传操作 因为通信故障会中断数据流。
如果您是使用客户端库的开发者，请注意有些客户端库 为可续传上传提供原生支持。
在以下情况下，请使用可续传上传选项：
- 您正在上传大型文件。
- 出现网络中断或某些其他传输故障的可能性为 高（例如，当您从移动应用上传文件时）。
有网络时，可续传上传也可以减少您的带宽使用量 失败了，因为您不必从 开头。
第 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，则表示上传
已经被终止。