本页介绍了如何通过 REST 协议向 Google 相册影视库 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]
多个数据块
以下示例中，所展示的可续传请求将使用断点续传会话网址，以及在上一步中获取的可接受的数据块尺寸粒度，从而以多个数据块的形式上传 3039417 字节的 JPEG 文件。此示例使用启动上传会话后，标头字段 x-goog-upload-chunk-granularity 中返回的数据块尺寸（262144 字节）。请注意，每次上传的数据中均包含 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
然后，您可以使用该偏移量继续上传。除非您发送上传和终止的组合命令，否则必须以服务器提供的偏移量继续上传。在此情况下，您也可使用值为 0 的偏移量继续上传。
如果查询命令的 HTTP 响应中出现 X-Goog-Upload-Status 标头且该值不是 active，则表示上传已终止。