执行可续传上传
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页介绍了如何在 Street View Publish API 中发出可续传上传请求。当数据流因通信故障而中断后，您可以利用此协议恢复上传操作。在以下情况下，请使用此选项：
- 您正在上传大型文件。
- 遇到网络中断或其他传输故障的可能性很高（例如，上传移动应用中的文件）。
出现网络故障时，断点续传还可减少带宽占用，这是因为您无需从头开始重新上传大型文件。
如果您要通过可靠的网络连接发送小型文件，则可改用简单上传。
启动可续传上传会话
获取 uploadUrl 后，您可以启动可续传上传会话：
- 创建一个针对
uploadUrl 的 POST 请求。
添加以下 HTTP 标头：
X-Goog-Upload-Protocol：设置为 resumable。X-Goog-Upload-Header-Content-Length：设置为后续请求中传输的文件数据的总字节数。X-Goog-Upload-Header-Content-Type：设为文件数据的 MIME 类型。X-Goog-Upload-Command：设置为 start。
发送请求。
示例：启动可续传上传会话
以下示例展示了如何启动可续传会话以上传新文件。在本例中，文件是图片，文件中的字节总数为 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
上传文件
借助以下两种方法，您可以使用可续传会话上传文件：
- 使用单一请求。此方法通常具有最佳的效果，因为它需要较少的请求，因此具有更好的性能。
- 使用多个数据块。如果您符合以下情况，请使用此方法：
- 您需要减少任何单一请求中传输的数据量。如果有固定的单个请求时间限制，您可能就需要这样做。
- 您需要提供自定义指示，以显示上传进度。
- 您需要知晓何时舍弃数据是安全的。
单个请求
如需使用单一请求上传文件，请执行以下操作：
- 创建一个针对可续传会话网址的
POST 请求。
- 将文件的数据添加到请求正文。
添加以下 HTTP 标头：
Content-Length：设置为文件中的字节数。X-Goog-Upload-Command：设置为 upload, finalize。
发送请求。
如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。
多个数据块
如需使用多个数据块上传文件，请执行以下操作：
- 创建一个针对可续传会话网址的
POST 请求。
- 将数据块的数据添加到请求正文。除了结束上传的最后一个数据块之外，数据块的大小应该是 2 MiB（兆比字节）的整数倍。请尽量使用较大的数据块，以便高效上传。
添加以下 HTTP 标头：
Content-Length：设置为数据块中的字节数。X-Goog-Upload-Command：设置为 upload。对于最后一个数据块，请将此标头设置为 upload, finalize。X-Goog-Upload-Offset：设置为应写入字节的偏移量。请注意，您必须连续上传字节。
发送请求。如果上传请求中断或者您收到 5xx 响应，请按照恢复中断的上传中的步骤操作。
对文件中剩余的每个数据块重复执行第 1 步到第 4 步。
示例：上传文件
单个请求
以下示例展示了一个可续传请求，该请求使用在上一步中获取的可续传会话网址，以单个请求的形式上传整个 4200000 字节的 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 状态代码，请查询服务器以了解上传进度：
- 创建一个针对可续传会话网址的
POST 请求。
- 将
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，则表示上传已终止。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2024-11-30。
[null,null,["最后更新时间 (UTC)：2024-11-30。"],[[["\u003cp\u003eResumable uploads are recommended for large files or unreliable network connections, allowing you to resume interrupted uploads without restarting from the beginning.\u003c/p\u003e\n"],["\u003cp\u003eTo initiate a resumable upload, send a POST request to the upload URL with specific headers, including \u003ccode\u003eX-Goog-Upload-Protocol\u003c/code\u003e, \u003ccode\u003eX-Goog-Upload-Header-Content-Length\u003c/code\u003e, \u003ccode\u003eX-Goog-Upload-Header-Content-Type\u003c/code\u003e, and \u003ccode\u003eX-Goog-Upload-Command\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eSave the resumable session URL from the response header \u003ccode\u003eX-Goog-Upload-URL\u003c/code\u003e to use in subsequent upload requests, which expires after 7 days.\u003c/p\u003e\n"],["\u003cp\u003eUpload the file either in a single request or in multiple chunks (multiples of 2 MiB), setting appropriate headers like \u003ccode\u003eContent-Length\u003c/code\u003e, \u003ccode\u003eX-Goog-Upload-Command\u003c/code\u003e, and \u003ccode\u003eX-Goog-Upload-Offset\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eIf an upload is interrupted, query the server with \u003ccode\u003eX-Goog-Upload-Command\u003c/code\u003e set to \u003ccode\u003equery\u003c/code\u003e to determine the received data size and resume the upload from that offset.\u003c/p\u003e\n"]]],["To make a resumable upload, first initiate a session by sending a `POST` request with headers like `X-Goog-Upload-Protocol: resumable`, `X-Goog-Upload-Header-Content-Length`, `X-Goog-Upload-Header-Content-Type`, and `X-Goog-Upload-Command: start`. The server responds with an `X-Goog-Upload-URL`. Upload the file in a single request with the `upload, finalize` command, or in multiple chunks with `upload` commands, using multiples of 2 MiB. If interrupted, query the server using `X-Goog-Upload-Command: query` to determine the current upload offset and resume accordingly.\n"],null,["# Performing a Resumable Upload\n\nThis page describes how to make a resumable upload request in the Street View\nPublish API. This protocol allows you to resume an upload operation after a\ncommunication failure interrupts the flow of data. Use this option if:\n\n- You are uploading large files.\n- The likelihood of network interruption or some other transmission failure is high (for example, if you are uploading a file from a mobile app).\n\nResumable uploads can also reduce your bandwidth usage when there is a network\nfailure, because you don't have to restart large file uploads from the\nbeginning.\n\nIf you are sending small files over a reliable network connection, you can use\na simple upload instead.\n\nInitiating a resumable upload session\n-------------------------------------\n\nAfter you have obtained an `uploadUrl`, you can initiate a resumable\nupload session:\n\n1. Create a `POST` request to the `uploadUrl`.\n2. Add the following HTTP headers:\n\n - `X-Goog-Upload-Protocol`: Set to `resumable`.\n - `X-Goog-Upload-Header-Content-Length`: Set to the total number of bytes of the file data, which will be transferred in subsequent requests.\n - `X-Goog-Upload-Header-Content-Type`: Set to the MIME type of the file data.\n - `X-Goog-Upload-Command`: Set to `start`.\n3. Send the request.\n\n### Example: Initiating a resumable upload session\n\nThe following example shows how to initiate a resumable session to upload a new\nfile. In this case, the file is an image and the total number of bytes in the\nfile is 4200000. Note that the body of the request is empty; therefore, the\n`Content-Length` header is set to 0. \n\n POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1\n Authorization: Bearer [YOUR_AUTH_TOKEN]\n Content-Length: 0\n X-Goog-Upload-Protocol: resumable\n X-Goog-Upload-Header-Content-Length: 4200000\n X-Goog-Upload-Header-Content-Type: image/jpeg\n X-Goog-Upload-Command: start\n\n[Saving the resumable session URL](#saving-resumable-session) describes how\nto handle the response for the request to initiate the resumable upload session.\n\nSaving the resumable session URL\n--------------------------------\n\nFor the request sent to initiate a resumable upload session, the server will\nreply with a `200 OK` HTTP status code, including the following header:\n\n- `X-Goog-Upload-URL`: A unique URL that must be used to complete the upload through all of the remaining requests.\n\n| **Note:** A resumable session URL expires after 7 days.\n\nCopy and save the resumable ression URL so that you can use it for subsequent\nrequests.\n\n### Example: Saving the resumable session URL\n\nThe following example shows a response that includes a resumable session URL and\na size granularity requirement. \n\n HTTP/1.1 200 OK\n X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable\n\nUploading the file\n------------------\n\nThere are two ways to upload a file with a resumable session:\n\n1. **In a single request.** This approach is usually best, because it requires fewer requests and thus has better performance.\n2. **In multiple chunks.** Use this approach if:\n - You need to reduce the amount of data transferred in any single request. You might need to do this when there is a fixed time limit for individual requests.\n - You need to provide a customized indicator showing the upload progress.\n - You need to know when it is safe to discard data.\n\n### Single Request\n\nTo upload the file in a single request:\n\n1. Create a `POST` request to the resumable session URL.\n2. Add the file's data to the request body.\n3. Add the following HTTP headers:\n\n - `Content-Length`: Set to the number of bytes in the file.\n - `X-Goog-Upload-Command`: Set to `upload, finalize`.\n4. Send the request.\n\nIf the upload request is interrupted or you receive a `5xx` response, follow\nthe procedure in [Resuming an interrupted upload](#resume-upload).\n\n### Multiple Chunks\n\nTo upload the file in multiple chunks:\n\n1. Create a `POST` request to the resumable session URL.\n2. Add the chunk's data to the request body. Create chunks in multiples of 2 MiB (mebibytes), except for the final chunk that completes the upload. Keep the chunk size as large as possible so that the upload is efficient.\n3. Add the following HTTP headers:\n\n - `Content-Length`: Set to the number of bytes in the chunk.\n - `X-Goog-Upload-Command`: Set to `upload`. For the last chunk, set to `upload, finalize`.\n - `X-Goog-Upload-Offset`: Set to the offset at which the bytes should be written. Note that the bytes must be uploaded serially.\n4. Send the request. If the upload request is interrupted or you receive a\n `5xx` response, follow the procedure in\n [Resuming an interrupted upload](#resume-upload).\n\n5. Repeat steps 1 through 4 for each remaining chunk in the file.\n\n### Example: Uploading the file\n\n### Single Request\n\nThe following example shows a resumable request to upload an entire\n4,200,000-byte JPEG file in a single request, using the resumable session\nURL obtained in the previous step: \n\n```\nPOST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1\nContent-Length: 4200000\nX-Goog-Upload-Command: upload, finalize\nX-Goog-Upload-Offset: 0\n\n[BYTES 0-4199999]\n```\n\nIf the request succeeds, you receive a `200 OK` HTTP status code.\n\n### Multiple Chunks\n\nThe following example shows a resumable request to upload a 4,200,000-byte\nJPEG file in multiple chunks, using the resumable session URL and the size\ngranularity obtained in the previous step. This example uses a chunk size of\n2097000 bytes, which is a multiple of 2 MiB (mebibytes).\n\nFirst chunk: \n\n```\nPOST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1\nContent-Length: 2097000\nX-Goog-Upload-Command: upload\nX-Goog-Upload-Offset: 0\n\n[BYTES 0-2096999]\n```\n\n\u003cbr /\u003e\n\nSecond chunk: \n\n```\nPOST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1\nContent-Length: 2097000\nX-Goog-Upload-Command: upload\nX-Goog-Upload-Offset: 2097000\n\n[BYTES 2097000-4193999]\n```\n\n\u003cbr /\u003e\n\nLast chunk: \n\n```\nPOST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1\nContent-Length: 6000\nX-Goog-Upload-Command: upload, finalize\nX-Goog-Upload-Offset: 4194000\n\n[BYTES 4194000-4200000]\n```\n\n\u003cbr /\u003e\n\nResuming an interrupted upload\n------------------------------\n\nIf the upload request is interrupted or if you receive a non-`200` HTTP status\ncode, query the server to find out how much of the upload succeeded:\n\n1. Create a `POST` request to the resumable session URL.\n2. Set the `X-Goog-Upload-Command` to `query`.\n3. Send the request.\n\nThe server will respond with a `200 OK` HTTP status code and the current size of the\nupload: \n\n HTTP/1.1 200 OK\n X-Goog-Upload-Status: active\n X-Goog-Upload-Size-Received: 100\n\nYou can then resume uploading at this offset. You must resume at the offset\nprovided by the server unless you send a combined upload and finalize command,\nin which case you can also resume at offset 0.\n\nIf the `X-Goog-Upload-Status` header in the HTTP response of your query command\nis present and the value is not `active`, then the upload has already been\nterminated."]]
