执行可续传上传

本页介绍了如何在 Street View Publish API 中发出可续传上传请求。当数据流因通信故障而中断后，您可以利用此协议恢复上传操作。在以下情况下，请使用此选项：

  • 您正在上传大型文件。
  • 遇到网络中断或其他传输故障的可能性很高（例如，上传移动应用中的文件）。

出现网络故障时，断点续传还可减少带宽占用，这是因为您无需从头开始重新上传大型文件。

如果您要通过可靠的网络连接发送小型文件，则可以改用简单上传。

启动可续传上传会话

获取 uploadUrl 后，您可以启动可续传上传会话：

  1. 创建一个针对 uploadUrl 的 POST 请求。

  2. 添加以下 HTTP 标头：

    • X-Goog-Upload-Protocol：设置为 resumable。
    • X-Goog-Upload-Header-Content-Length：设置为后续请求中传输的文件数据的总字节数。
    • X-Goog-Upload-Header-Content-Type：设为文件数据的 MIME 类型。
    • X-Goog-Upload-Command：设置为 start。

  3. 发送请求。

示例：启动可续传上传会话

以下示例展示了如何启动可续传会话以上传新文件。在本例中，文件是图片，文件中的字节总数为 4200000。请注意，请求正文为空；因此，Content-Length 标头设置为 0。

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

保存可续传会话网址介绍了如何处理用于启动可续传上传会话的请求的响应。

正在保存可续传会话网址

对于发送以启动可续传上传会话的请求，服务器将回复 200 OK HTTP 状态代码，其中包含以下标头：

  • X-Goog-Upload-URL：一个唯一网址，您必须使用该网址通过所有剩余的请求完成上传。

请复制并保存可续传会话网址，以便在后续请求中使用。

示例：保存可续传会话网址

以下示例展示了一个响应，其中包含可续传会话网址和大小粒度要求。

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

上传文件

借助以下两种方法，您可以使用可续传会话上传文件：

  1. 使用单一请求。此方法通常具有最佳的效果，因为它需要较少的请求，因此具有更好的性能。
  2. 使用多个数据块。如果您符合以下情况，请使用此方法：
    • 您需要减少任一单个请求中传输的数据量。 如果有固定的单个请求时间限制，您可能就需要这样做。
    • 您需要提供自定义指示，以显示上传进度。
    • 您需要知晓何时舍弃数据是安全的。

单个请求

如需使用单一请求上传文件，请执行以下操作：

  1. 创建一个针对可续传会话网址的 POST 请求。
  2. 将文件的数据添加到请求正文。

  3. 添加以下 HTTP 标头：

    • Content-Length：设置为文件中的字节数。
    • X-Goog-Upload-Command：设置为 upload, finalize。

  4. 发送请求。

如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。

多个数据块

如需使用多个数据块上传文件，请执行以下操作：

  1. 创建一个针对可续传会话网址的 POST 请求。
  2. 将数据块的数据添加到请求正文。除了结束上传的最后一个数据块之外，数据块的大小应该是 2 MiB（兆比字节）的整数倍。请尽量使用较大的数据块，以便高效上传。

  3. 添加以下 HTTP 标头：

    • Content-Length：设置为数据块中的字节数。
    • X-Goog-Upload-Command：设置为 upload。对于最后一个数据块，请将此标头设置为 upload, finalize。
    • X-Goog-Upload-Offset：设置为应写入字节的偏移量。请注意，您必须连续上传字节。

  4. 发送请求。如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。

  5. 对文件中剩余的每个数据块重复执行第 1 步到第 4 步。

示例：上传文件

单个请求

以下示例展示了一个可续传请求，该请求使用在上一步中获得的可续传会话网址在单个请求中上传整个 4,200,000 字节的 JPEG 文件：

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

如果请求成功，您将收到 200 OK HTTP 状态代码。

多个数据块

以下示例中，所展示的可续传请求将使用断点续传会话网址，以及在上一步中获取的大小粒度，从而以多个数据块的形式上传 420 万字节的 JPEG 文件。此示例使用的块大小为 2097000 字节，是 2 MiB（兆比字节）的倍数。

第一个数据块： 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

第二个数据块： 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

最后一个数据块： 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

恢复中断的上传

如果上传请求中断或您收到非 200 HTTP 状态代码，请查询服务器以了解上传进度：

  1. 创建针对可续传会话网址的 POST 请求。
  2. 将 X-Goog-Upload-Command 设置为 query。
  3. 发送请求。

服务器将返回 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，则表示上传已终止。