本页面介绍如何在 Cloud Storage JSON 和 XML API 中发出可续传上传请求。当数据流因通信故障而中断后,您可以利用此协议恢复上传操作。
启动可续传上传会话
如需启动可续传上传会话,请执行以下操作:
JSON API
- 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。
(可选)创建一个
.json
文件,其中包含您要在上传的对象上设置的元数据。使用
cURL
,通过POST
Object 请求调用 JSON API:curl -i -X POST --data-binary @METADATA_LOCATION \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ -H "Content-Length: INITIAL_REQUEST_LENGTH" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"
其中:
METADATA_LOCATION
是 JSON 文件的本地路径,其中包含您在上一步中指定的可选元数据。如果您不添加元数据文件,请排除此文件以及--data-binary @
和Content-Type
标头。OAUTH2_TOKEN
是您在第 1 步中生成的访问令牌。INITIAL_REQUEST_LENGTH
是此初始请求正文中的字节数,例如79
。如果您采用的是分块传输编码,则不需要进行此操作。BUCKET_NAME
是对象要上传到的存储分区的名称。例如my-bucket
。OBJECT_NAME
是您要为对象指定的名称。例如pets/dog.png
。如果您在第 2 步的对象元数据文件中添加了name
,则不需要此名称。
如果您启用了跨域资源共享,则还应在此上传请求和后续上传请求中添加
Origin
标头。您可以向请求添加的可选标头包括
X-Upload-Content-Type
和X-Upload-Content-Length
。如果成功,响应将包含
200
状态代码。将响应的
Location
标头中提供的可续传会话 URI 保存到POST
Object 请求中。上传对象数据的后续请求会用到此 URI。
XML API
- 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。
使用
cURL
,通过正文为空的POST
Object 请求调用 XML API:curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Length: 0" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-resumable: start" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
其中:
OAUTH2_TOKEN
是您在第 1 步中生成的访问令牌。OBJECT_CONTENT_TYPE
是该对象的内容类型,例如image/png
。如果您不指定内容类型,Cloud Storage 系统会将对象的Content-Type
元数据设置为application/octet-stream
。BUCKET_NAME
是对象要上传到的存储分区的名称。例如my-bucket
。OBJECT_NAME
是您要为对象指定的名称。例如pets/dog.png
。
如果您启用了跨域资源共享,则还应在此上传请求和后续上传请求中添加
Origin
标头。如果成功,响应将包含
201
状态消息。将响应的
Location
标头中提供的可续传会话 URI 保存到POST
Object 请求中。上传对象数据的后续请求会用到此 URI。
上传文件
启动可续传上传后,您可以通过以下两种方法上传对象的数据:
- 在单个请求中:此方法通常最理想,因为它需要的请求更少,所以性能也更高。
- 在多个区块中:如果您需要减少单个请求中传输的数据量(例如,单个请求有固定时间限制时),或在上传开始时不了解上传操作的总大小。
单一请求上传
如需使用单一请求上传文件,请执行以下操作:
JSON API
XML API
如果上传全部完成,您会收到 200 OK
或 201 Created
响应,以及与资源相关联的任何元数据。
如果上传请求中断或者您收到 5xx
响应,请按照恢复中断的上传中的步骤操作。
多个数据块上传
如需使用多个数据块上传文件,请执行以下操作:
JSON API
根据您要上传的文件创建数据块。
数据块的大小应该是 256 KiB(256 x 1024 字节)的整数倍,除非数据块是结束上传的最后一个数据块。较大的数据块大小通常可使上传更高效。我们建议您使用 8 MiB 作为数据块大小。
使用
cURL
,通过PUT
Object 请求调用 JSON API:curl -i -X PUT --data-binary @CHUNK_LOCATION \ -H "Content-Length: CHUNK_SIZE" \ -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
其中:
CHUNK_LOCATION
是您当前正在上传的数据块的本地路径。CHUNK_SIZE
是您正在当前请求中上传的字节数。例如524288
。CHUNK_FIRST_BYTE
是您正在上传的数据块包含的整个对象中的起始字节。CHUNK_LAST_BYTE
是您正在上传的数据块包含的整个对象中的结束字节。TOTAL_OBJECT_SIZE
是您正在上传的对象的总大小。SESSION_URI
是您在启动可续传上传时Location
标头中返回的值。
Content-Range
的一个示例为Content-Range: bytes 0-524287/2000000
。如需详细了解此标头,请参阅Content-Range
。如果请求成功,服务器会返回
308 Resume Incomplete
。响应包含Range
标头。使用此标头中的上限值来确定从何处开始上传下一个数据块。不应假定服务器已收到请求中发送的所有字节。对您要上传的数据的每个剩余数据块重复执行上述步骤。
XML API
根据您要上传的文件创建数据块。
数据块的大小应该是 256 KiB(256 x 1024 字节)的整数倍,除非数据块是结束上传的最后一个数据块。较大的数据块大小通常可使上传更高效。我们建议您使用 8 MiB 作为数据块大小。
使用
cURL
,通过PUT
Object 请求调用 XML API:curl -i -X PUT --data-binary @CHUNK_LOCATION \ -H "Content-Length: CHUNK_SIZE" \ -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
其中:
CHUNK_LOCATION
是您当前正在上传的数据块的本地路径。CHUNK_SIZE
是您正在当前请求中上传的字节数。例如524288
。CHUNK_FIRST_BYTE
是您正在上传的数据块包含的整个对象中的起始字节。CHUNK_LAST_BYTE
是您正在上传的数据块包含的整个对象中的结束字节。TOTAL_OBJECT_SIZE
是您正在上传的对象的总大小。SESSION_URI
是您在启动可续传上传时Location
标头中返回的值。
Content-Range
的一个示例为Content-Range: bytes 0-524287/2000000
。如需详细了解此标头,请参阅Content-Range
。如果请求成功,服务器会返回
308 Resume Incomplete
。响应包含Range
标头。使用此标头中的上限值来确定从何处开始上传下一个数据块。不应假定服务器已收到请求中发送的所有字节。对您要上传的数据的每个剩余数据块重复执行上述步骤。
上传全部完成后,您会收到 200 OK
或 201 Created
响应,以及与资源相关联的任何元数据。
如果任何数据块上传中断或者您收到 5xx
响应,请按照恢复中断的上传中的步骤操作。
检查可续传上传的状态
如果您的可续传上传中断或者您不确定上传已完成,则可以检查上传的状态:
JSON API
XML API
200 OK
或 201 Created
响应表明上传已完成,无需执行进一步操作。
308 Resume Incomplete
响应表明您需要继续上传文件。
- 如果 Cloud Storage 尚未收到任何字节,则
308
响应没有Range
标头。在这种情况下,您应从头开始上传。 - 否则,
308
响应具有Range
标头,该标头表明 Cloud Storage 目前已收到哪些字节。在恢复中断的上传时,请使用此值。
恢复中断的上传
如果上传请求在收到响应之前被终止,或者您收到 503
或 500
响应,则需要从中断的地方恢复中断的上传。如需恢复中断的上传,请执行以下操作:
JSON API
将响应中包含的
Range
标头的上限值保存到您的状态检查中。如果响应没有Range
标头,则 Cloud Storage 尚未收到任何字节,您应从头开始上传。确保您要上传的对象数据从
Range
标头中的上限值后面的字节开始。使用
cURL
,通过PUT
Object 请求(该请求从Range
标头中的值后面的字节开始上传数据)调用 JSON API:curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \ -H "Content-Length: UPLOAD_SIZE_REMAINING" \ -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
其中:
PARTIAL_OBJECT_LOCATION
是您要上传的数据剩余部分的本地路径。UPLOAD_SIZE_REMAINING
是您正在当前请求中上传的字节数。例如,如果总大小为 20000000 的对象在上传字节 0-42 后中断,则上传该对象剩余部分时的UPLOAD_SIZE_REMAINING
为1999957
。NEXT_BYTE
是您在第 2 步中保存的值后的下一个整数。例如,如果42
是第 2 步中的上限值,则NEXT_BYTE
的值为43
。LAST_BYTE
是此PUT
请求中包含的结束字节。例如,为了上传完总大小为20000000
的对象,LAST_BYTE
的值为1999999
。TOTAL_OBJECT_SIZE
是您正在上传的对象的总大小。例如20000000
。SESSION_URI
是您在启动可续传上传时Location
标头中返回的值。
XML API
将响应中包含的
Range
标头的上限值保存到您的状态检查中。如果响应没有Range
标头,则 Cloud Storage 尚未收到任何字节,您应从头开始上传。确保您要上传的对象数据从
Range
标头中的上限值后面的字节开始。使用
cURL
,通过PUT
Object 请求(该请求从Range
标头中的值后面的字节开始上传数据)调用 XML API:curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \ -H "Content-Length: UPLOAD_SIZE_REMAINING" \ -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
其中:
PARTIAL_OBJECT_LOCATION
是您要上传的数据剩余部分的本地路径。UPLOAD_SIZE_REMAINING
是您正在当前请求中上传的字节数。例如,如果总大小为 20000000 的对象在上传字节 0-42 后中断,则上传该对象剩余部分时的UPLOAD_SIZE_REMAINING
为1999957
。NEXT_BYTE
是您在第 2 步中保存的值后的下一个整数。例如,如果42
是第 2 步中的上限值,则NEXT_BYTE
的值为43
。LAST_BYTE
是此PUT
请求中包含的结束字节。例如,为了上传完总大小为20000000
的对象,LAST_BYTE
的值为1999999
。TOTAL_OBJECT_SIZE
是您正在上传的对象的总大小。例如20000000
。SESSION_URI
是您在启动可续传上传时Location
标头中返回的值。
您可以在会话 URI 处于活动状态时根据需要恢复上传;会话 URI 将在一周后过期。文件上传成功后,Cloud Storage 会返回 200 OK
或 201 created
状态代码。
取消上传
如需取消可续传上传并阻止对其执行任何进一步操作,请执行以下操作:
JSON API
XML API
如果成功,响应将包含 499
状态代码。进一步尝试查询或恢复上传将导致 4xx
响应。
后续步骤
- 详细了解可续传上传。
- 阅读 JSON API 和 XML API 概览。
- 流式上传未知大小的对象。
- 了解如何向 Cloud Storage JSON API 批量发送多个请求。