执行可续传上传

本页介绍了如何在 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 步。

示例：上传文件

单一请求

以下示例展示了一个可续传请求，该请求使用在上一步中获取的可续传会话网址，在单个请求中上传整个 420 万字节的 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，则表示上传已经终止。