执行可续传上传

转到概念

本页面介绍如何在 Cloud Storage JSON 和 XML API 中发出可续传上传请求。当数据流因通信故障而中断后，您可以利用此协议恢复上传操作。

启动可续传上传会话

如需启动可续传上传会话，请执行以下操作：

JSON API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。

  2. （可选）创建一个 .json 文件，其中包含您要在上传的对象上设置的元数据。

  3. 使用 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 状态代码。

  4. 将响应的 Location 标头中提供的可续传会话 URI 保存到 POST Object 请求中。

    上传对象数据的后续请求会用到此 URI。

XML API

  1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。

  2. 使用 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 状态消息。

  3. 将响应的 Location 标头中提供的可续传会话 URI 保存到 POST Object 请求中。

    上传对象数据的后续请求会用到此 URI。

上传文件

启动可续传上传后，您可以通过以下两种方法上传对象的数据：

  • 使用单一请求：此方法通常具有最佳的效果，因为它需要较少的请求，因此具有更好的性能。
  • 使用多个数据块：如果您需要减少任何单一请求中传输的数据量（例如在单个请求有固定时间限制时），或者您在上传开始时不知道上传的总大小，请使用此方法。

单一请求上传

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

JSON API

  1. 使用 cURL，通过 PUT Object 请求调用 JSON API：

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_LOCATION 是对象的本地路径。例如 Desktop/dog.png。
    • OBJECT_SIZE 是对象中的字节数。例如 20000000。
    • SESSION_URI 是您在启动可续传上传时 Location 标头中返回的值。

XML API

  1. 使用 cURL，通过 PUT Object 请求调用 XML API：

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_LOCATION 是对象的本地路径。例如 Desktop/dog.png。
    • OBJECT_SIZE 是对象中的字节数。例如 20000000。
    • SESSION_URI 是您在启动可续传上传时 Location 标头中返回的值。

如果上传全部完成，您会收到 200 OK 或 201 Created 响应，以及与资源相关联的任何元数据。

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

多个数据块上传

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

JSON API

  1. 根据您要上传的文件创建数据块。

    数据块的大小应该是 256 KiB（256 x 1024 字节）的整数倍，除非数据块是结束上传的最后一个数据块。较大的数据块大小通常可使上传更高效。我们建议您使用 8 MiB 作为数据块大小。

  2. 使用 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 标头。使用此标头中的上限值来确定从何处开始上传下一个数据块。不应假定服务器已收到请求中发送的所有字节。

  3. 对您要上传的数据的每个剩余数据块重复执行上述步骤。

XML API

  1. 根据您要上传的文件创建数据块。

    数据块的大小应该是 256 KiB（256 x 1024 字节）的整数倍，除非数据块是结束上传的最后一个数据块。较大的数据块大小通常可使上传更高效。我们建议您使用 8 MiB 作为数据块大小。

  2. 使用 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 标头。使用此标头中的上限值来确定从何处开始上传下一个数据块。不应假定服务器已收到请求中发送的所有字节。

  3. 对您要上传的数据的每个剩余数据块重复执行上述步骤。

上传全部完成后，您会收到 200 OK 或 201 Created 响应，以及与资源相关联的任何元数据。

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

检查可续传上传的状态

如果您的可续传上传中断或者您不确定上传已完成，则可以检查上传的状态：

JSON API

  1. 使用 cURL，通过 PUT Object 请求调用 XML API：

    curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBEJCT_SIZE 是对象中的字节总数。如果您不知道对象的完整大小，请使用 * 作为此值。
    • SESSION_URI 是您在启动可续传上传时 Location 标头中返回的值。

XML API

  1. 使用 cURL，通过 PUT Object 请求调用 XML API：

    curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBEJCT_SIZE 是对象中的字节总数。如果您不知道对象的完整大小，请使用 * 作为此值。
    • SESSION_URI 是您在启动可续传上传时 Location 标头中返回的值。

200 OK 或 201 Created 响应表明上传已完成，无需执行进一步操作。

308 Resume Incomplete 响应表明您需要继续上传文件。

  • 如果 Cloud Storage 尚未收到任何字节，则 308 响应没有 Range 标头。在这种情况下，您应从头开始上传。
  • 否则，308 响应具有 Range 标头，该标头表明 Cloud Storage 目前已收到哪些字节。在恢复中断的上传时，请使用此值。

恢复中断的上传

如果上传请求在收到响应之前被终止，或者您收到 503 或 500 响应，则您需要从中断的地方恢复中断的上传。如需恢复中断的上传，请执行以下操作：

JSON API

  1. 检查您的可续传上传的状态。

  2. 将响应中包含的 Range 标头的上限值保存到您的状态检查中。如果响应没有 Range 标头，则 Cloud Storage 尚未收到任何字节，您应从头开始上传。

  3. 确保您要上传的对象数据从 Range 标头中的上限值后面的字节开始。

  4. 使用 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

  1. 检查您的可续传上传的状态。

  2. 将响应中包含的 Range 标头的上限值保存到您的状态检查中。如果响应没有 Range 标头，则 Cloud Storage 尚未收到任何字节，您应从头开始上传。

  3. 确保您要上传的对象数据从 Range 标头中的上限值后面的字节开始。

  4. 使用 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 标头中返回的值。

您可以根据需要多次恢复上传，但在重试请求时，请遵循可续传上传的重试准则。

文件上传成功后，Cloud Storage 会返回 200 OK 或 201 created 状态代码。

取消上传

如需取消可续传上传并阻止对其执行任何进一步操作，请执行以下操作：

JSON API

  1. 使用 cURL，通过 DELETE 请求调用 JSON API：

    curl -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    其中：

XML API

  1. 使用 cURL，通过 DELETE 请求调用 XML API：

    curl -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    其中：

如果成功，响应将包含 499 状态代码。进一步尝试查询或恢复上传将导致 4xx 响应。

后续步骤