使用Play游戏服务发布API上传图片

Play游戏服务发布API允许您为游戏资源上传图片。

上传选项

Play游戏服务发布API允许您上传某些类型的二进制数据或媒体。您可以上传的数据的具体特征在任何支持媒体上传的方法的参考页面上指定

• 最大上传文件大小：您可以使用此方法存储的最大数据量。

• 接受的媒体MIME类型：您可以使用此方法存储的二进制数据类型。

您可以通过以下任何一种方式发出上传请求。使用uploadType请求参数指定您正在使用的方法。

• 简单上传：uploadType=media。用于快速传输较小的文件，例如5 MB或更少。

• 分段上传：uploadType=multipart。用于快速传输较小的文件和元数据；将文件与其描述的元数据一起传输，全部在一个请求中。

• 可恢复上传：uploadType=resumable。用于可靠传输，尤其是在传输较大的文件时很重要。使用此方法，您将使用会话初始化请求，该请求可以选择包含元数据。对于大多数应用程序，这是一种很好的策略，因为它也可以以每个上传一个额外的HTTP请求为代价来处理较小的文件。

上传媒体时，您将使用特殊的URI。实际上，支持媒体上传的方法有两个URI端点

• 用于媒体的/upload URI。上传端点的格式是标准资源URI，前面带有“/upload”前缀。在传输媒体数据本身时使用此URI。

  示例：POST /upload/games/v1configuration/images/resourceId/imageType/imageType

• 用于元数据的标准资源URI。如果资源包含任何数据字段，则这些字段用于存储描述上传文件的元数据。在创建或更新元数据值时可以使用此URI。

  示例：POST /games/v1configuration/images/resourceId/imageType/imageType

简单上传

上传文件最直接的方法是发出简单的上传请求。如果以下情况之一为真，则此选项是一个不错的选择

• 文件足够小，如果连接失败，可以再次完整上传。

• 没有要发送的元数据。如果您计划在单独的请求中发送此资源的元数据，或者不支持或没有可用的元数据，则可能为真。要使用简单上传，请向方法的/upload URI发出POST或PUT请求，并添加查询参数uploadType=media。例如

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

发出简单上传请求时要使用的HTTP标头包括

• Content-Type。设置为方法接受的上传媒体数据类型之一，在发布API 参考中指定。

• Content-Length。设置为要上传的字节数。如果您使用的是分块传输编码，则不需要。

示例：简单上传

以下示例显示了Play游戏服务发布API中简单上传请求的使用。

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

如果请求成功，服务器将返回HTTP 200 OK状态代码以及任何元数据。例如

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

分段上传

如果您有要与要上传的数据一起发送的元数据，则可以发出单个multipart/related请求。如果要发送的数据足够小，以便在连接失败时可以再次完整上传，则这是一个不错的选择。

要使用分段上传，请向方法的/upload URI发出POST或PUT请求，并添加查询参数uploadType=multipart。例如

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

发出分段上传请求时要使用的顶级HTTP标头包括

-Content-Type。设置为multipart/related，并包含用于识别请求部分的边界字符串。

-Content-Length。设置为请求正文中的总字节数。请求的媒体部分必须小于为此方法指定的最大文件大小。

请求的正文格式化为multipart/related内容类型RFC2387，并包含正好两个部分。这些部分由边界字符串识别，最后一个边界字符串后面跟着两个连字符。

分段请求的每个部分都需要一个额外的Content-Type标头

• 元数据部分：必须放在第一位，并且Content-Type必须与接受的元数据格式之一匹配。

• 媒体部分：必须放在第二位，并且Content-Type必须与方法接受的媒体MIME类型之一匹配。

有关每个方法的接受的媒体MIME类型列表和上传文件的尺寸限制，请参阅发布API 参考。

示例：分段上传

以下示例显示了Play游戏服务发布API的分段上传请求。

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

如果请求成功，服务器将返回HTTP 200 OK状态代码以及任何元数据

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

可恢复上传

要更可靠地上传数据文件，您可以使用可恢复上传协议。此协议允许您在通信故障中断数据流后恢复上传操作。如果您正在传输大型文件并且网络中断或其他传输故障的可能性很高，例如从移动客户端应用程序上传时，它特别有用。如果发生网络故障，它还可以减少您的带宽使用量，因为您不必从头开始重新启动大型文件上传。

使用可恢复上传的步骤包括

1. 启动可恢复会话。向包含元数据（如果有）的上传URI发出初始请求。

2. 保存可恢复会话URI。保存初始请求响应中返回的会话URI；您将在本会话的其余请求中使用它。上传文件。

3. 将媒体文件发送到可恢复会话URI。

此外，使用可恢复上传的应用程序需要具有恢复中断上传的代码。如果上传中断，请找出已成功接收的数据量，然后从该点开始恢复上传。

启动可恢复会话

要启动可恢复上传，请向方法的 /upload URI 发出 POST 或 PUT 请求，并添加查询参数 uploadType=resumable。例如：

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

对于此初始化请求，请求体可以为空或仅包含元数据；您将在后续请求中传输要上传的文件的实际内容。

使用以下 HTTP 标头与初始请求一起使用

• X-Upload-Content-Type。设置为将在后续请求中传输的上传数据的媒体 MIME 类型。

• X-Upload-Content-Length。设置为将在后续请求中传输的上传数据的大小（以字节为单位）。如果在发出此请求时长度未知，则可以省略此标头。

• 如果提供元数据：Content-Type。根据元数据的类型设置。

• Content-Length。设置为在此初始请求的请求体中提供的数据大小（以字节为单位）。如果您使用 分块传输编码，则不需要。

请参阅发布 API 的 参考，以获取每个方法的已接受媒体 MIME 类型和上传文件大小限制列表。

示例：可恢复会话初始化请求

以下示例演示如何为 Play 游戏服务发布 API 启动可恢复会话。

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

下一部分介绍如何处理响应。

保存可恢复会话 URI

如果会话初始化请求成功，API 服务器将返回 200 OK HTTP 状态代码。此外，它还提供一个 Location 标头，用于指定可恢复会话 URI。如下例所示，Location 标头包含一个 upload_id 查询参数部分，该部分提供了用于此会话的唯一上传 ID。

示例：可恢复会话初始化响应

这是对步骤 1 中请求的响应

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

如上例响应所示，Location 标头的值是您将用作 HTTP 端点以执行实际文件上传或查询上传状态的会话 URI。

复制并保存会话 URI，以便您可以将其用于后续请求。

上传文件

要上传文件，请向您在上一步中获得的上传 URI 发送 PUT 请求。上传请求的格式为

PUT session_uri

在发出可恢复文件上传请求时要使用的 HTTP 标头包括 Content-Length。将其设置为在此请求中上传的字节数，这通常是上传文件的大小。

示例：可恢复文件上传请求

这是一个可恢复请求，用于上传当前示例的整个 2,000,000 字节 PNG 文件。

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

如果请求成功，服务器将返回 HTTP 201 Created，以及与此资源关联的任何元数据。如果可恢复会话的初始请求是 PUT（用于更新现有资源），则成功响应将为 200 OK，以及与此资源关联的任何元数据。

如果上传请求中断，或者如果您从服务器收到 HTTP 503 Service Unavailable 或任何其他 5xx 响应，请按照 恢复中断的上传 中概述的过程操作。

分块上传文件

使用可恢复上传，您可以将文件分成块，并发送一系列请求按顺序上传每个块。这不是首选方法，因为与其他请求相关的性能成本，并且通常不需要。但是，您可能需要使用分块来减少单个请求中传输的数据量。当单个请求存在固定时间限制时，这很有帮助，例如某些类别的 Google App Engine 请求。它还可以让您为默认情况下不支持上传进度的旧版浏览器提供上传进度指示。

如果您正在分块上传数据，则除了完整文件上传所需的 Content-Length 标头之外，还需要 Content-Range 标头。

• Content-Length。设置为块大小或可能更小，例如最后一个请求的情况。

• Content-Range。设置为显示您正在上传的文件中的哪些字节。例如，Content-Range: bytes 0-524287/2000000 表示您正在提供 2,000,000 字节文件中前 524,288 字节（256 x 1024 x 2）。

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

恢复中断的上传

如果上传请求在收到响应之前终止，或者如果您从服务器收到 HTTP 503 Service Unavailable 响应，则需要恢复中断的上传。要恢复中断的上传，请执行以下操作

1. 请求状态。通过向上传 URI 发出空的 PUT 请求来查询上传的当前状态。对于此请求，HTTP 标头应包含一个 Content-Range 标头，指示文件中当前位置未知。例如，如果文件总长度为 2,000,000，则将 Content-Range 设置为 */2000000。如果您不知道文件的完整大小，请将 Content-Range 设置为 */*。

2. 获取已上传的字节数。处理状态查询的响应。服务器在其响应中使用 Range 标头来指定迄今为止已接收到的字节。例如，Range 标头为 0-299999 表示已收到文件的前 300,000 字节。

3. 上传剩余数据。最后，既然您知道在哪里恢复请求，请发送剩余数据或当前块。请注意，无论哪种情况，您都需要将剩余数据视为一个单独的块，因此在恢复上传时需要发送 Content-Range 标头。

示例：恢复中断的上传

1. 请求上传状态。以下请求使用 Content-Range 标头指示 2,000,000 字节文件中当前位置未知。

   PUT {session_uri} HTTP/1.1
   Content-Length: 0
   Content-Range: bytes */2000000
   

2. 从响应中提取迄今为止上传的字节数。服务器的响应使用Range标头指示它已收到文件的前 43 个字节。使用 Range 标头的上限值来确定恢复上传的起始位置。

   HTTP/1.1 308 Resume Incomplete
   Content-Length: 0
   Range: 0-42
   

3. 从中断的地方恢复上传。以下请求通过发送文件的其余字节（从第 43 个字节开始）来恢复上传。

   PUT {session_uri} HTTP/1.1
   Content-Length: 1999957
   Content-Range: bytes 43-1999999/2000000
   
   bytes 43-1999999
   

错误处理

上传媒体时，了解一些与错误处理相关的最佳实践很有帮助。

• 恢复或重试由于连接中断或任何 5xx 错误而导致失败的上传，包括

  • 500 内部服务器错误
  • 502 网关错误
  • 503 服务不可用
  • 504 网关超时

• 如果在恢复或重试上传请求时返回任何5xx服务器错误，请使用指数退避策略。如果服务器过载，可能会发生这些错误。指数退避可以帮助在请求量大或网络流量繁重期间缓解此类问题。

• 其他类型的请求不应通过指数退避处理，但您仍然可以重试其中一些请求。重试这些请求时，请限制重试次数。例如，您的代码可以在报告错误之前将其限制为十次或更少次重试。

• 在进行可恢复上传时，处理404 Not Found和410 Gone错误，方法是从头开始整个上传。

指数退避

指数退避是一种网络应用程序的标准错误处理策略，其中客户端定期在越来越长的时间内重试失败的请求。如果大量请求或繁重的网络流量导致服务器返回错误，则指数退避可能是处理这些错误的好策略。相反，对于与网络容量或响应时间无关的错误（例如无效的授权凭据或文件未找到错误），它不是相关的策略。

正确使用指数退避可以提高带宽使用效率，减少获得成功响应所需的请求数量，并在并发环境中最大化请求吞吐量。

实现简单指数退避的流程如下

1. 向 API 发出请求。
2. 收到HTTP 503响应，表示您应该重试请求。
3. 等待 1 秒 + random_number_milliseconds 并重试请求。
4. 收到HTTP 503响应，表示您应该重试请求。
5. 等待 2 秒 + random_number_milliseconds，并重试请求。
6. 收到HTTP 503响应，表示您应该重试请求。
7. 等待 4 秒 + random_number_milliseconds，并重试请求。
8. 收到HTTP 503 响应，表示您应该重试请求。
9. 等待 8 秒 + random_number_milliseconds，并重试请求。
10. 收到HTTP 503 响应，表示您应该重试请求。
11. 等待 16 秒 + random_number_milliseconds，并重试请求。
12. 停止。报告或记录错误。

在上面的列表中，random_number_milliseconds 是一个小于或等于 1000 的随机毫秒数。这是必要的，因为引入一个小随机延迟有助于更均匀地分配负载并避免服务器可能出现拥塞。random_number_milliseconds 的值必须在每次等待后重新定义。

该算法设置为在 n 为 5 时终止。此上限可以防止客户端无限重试，并且导致在请求被视为“不可恢复错误”之前总延迟约 32 秒。更大的最大重试次数是可以的，尤其是在进行长时间上传时；只需确保将重试延迟限制在合理范围内，例如，少于一分钟。

API 客户端库指南

• .NET

• Java

• PHP

• Python

• Ruby