正在上传附件

借助 Gmail API，您可以在创建或更新草稿时，或在插入或发送邮件时上传文件数据。

上传选项

借助 Gmail API，您可以上传特定类型的二进制数据或媒体。您可以上传的数据的具体特性，都已在任何支持媒体上传功能的方法的参考页面中指定：

  • 上传文件的大小上限：使用该方法可以存储的数据量上限。
  • 接受的媒体 MIME 类型：使用该方法可以存储的二进制数据类型。

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

  • 简单上传：uploadType=media。适用于快速传输较小的文件，例如 5 MB 或更小的文件。
  • 多部分上传：uploadType=multipart。用于快速传输较小的文件和元数据；需在同一个请求中传输相应文件以及用于描述该文件的元数据。
  • 可续传上传：uploadType=resumable用于进行可靠的传输；该方法对于传输较大的文件尤为重要。通过这种方法，您可以使用一个启动请求的会话，可以选择在其中包含元数据。对于绝大多数应用来说，这是一个很好的策略，因为该方法也适用于传输较小的文件（只不过每次上传时都要多发出一个 HTTP 请求）。

上传媒体时，您需要使用一个特殊的 URI。事实上，所有支持媒体上传功能的方法都具有以下两个 URI 端点：

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

    示例：POST /upload/gmail/v1/users/userId/messages/send

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

    示例：POST /gmail/v1/users/userId/messages/send

简单上传

上传文件最简单的方法就是发出简单上传请求。在以下情况下，此选项会是理想之选：

  • 文件非常小，就算连接失败后需要再次完整上传也没关系。
  • 没有元数据要发送。如果打算在单独的请求中发送相应资源的元数据，或者元数据不受支持或不存在，就可能没有元数据要发送。

如需使用简单上传，请针对该方法的 /upload URI 发出 POST 或 PUT 请求，并在请求中添加查询参数 uploadType=media。例如：

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

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

  • Content-Type。请将此项设为该方法接受的某种上传媒体数据类型（具体请参阅 API 参考文档）。
  • Content-Length。请将此项设为您要上传的字节数。如果您采用的是分块传输编码，则不需要进行此操作。

示例：简单上传

以下示例展示了如何针对 Gmail API 使用简单上传请求。

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

多部分上传

如果您有要随上传的数据一起发送的元数据，则可以发出一个 multipart/related 请求。如果您要发送的数据小到能够在连接失败时再次完整上传，那么该方法便是您的理想之选。

如需使用多部分上传，请向该方法的 /upload URI 发出 POST 或 PUT 请求，并在请求中添加查询参数 uploadType=multipart。例如：

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

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

  • Content-Type。将此项设为 multipart/related，并在其中添加您要用于标识请求各个部分的定界字符串。
  • Content-Length。将此项设为请求正文中的字节总数。该请求的媒体部分必须小于为该方法指定的文件大小上限。

该请求的正文采用 multipart/related 内容类型 [RFC2387] 的格式，且恰好包含两个部分。这两个部分由定界字符串标识，最后的定界字符串后跟两个连字符。

分段请求的每个部分都需要附加一个 Content-Type 标头：

  1. 元数据部分：必须位于第一部分，且 Content-Type 必须与该方法接受的某一元数据格式匹配。
  2. 媒体部分：必须位于第二部分，且 Content-Type 必须与该方法接受的某一媒体 MIME 类型匹配。

请参阅 API 参考，了解每个方法接受的媒体 MIME 类型的列表以及上传文件的大小限制。

注意：如需仅创建或更新元数据部分，而不上传关联数据，只需向标准资源端点发送 POST 或 PUT 请求：https://www.googleapis.com/gmail/v1/users/userId/messages/send

示例：分段上传

以下示例展示了 Gmail API 的分块上传请求。

POST /upload/gmail/v1/users/userId/messages/send?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

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

可续传上传

如需更可靠地上传数据文件，您可以使用“可续传上传”协议。利用该协议，您可以在因通信故障导致数据流中断之后恢复上传操作。如果您要传输大型文件，并且发生网络中断或某些其他传输故障的几率较高（例如，通过移动客户端应用上传时），您会发现该协议特别实用。此外，它还可以在发生网络故障时减少您的带宽使用量，因为您不必从头开始重新上传大型文件。

如需使用可续传上传，请按以下步骤操作：

  1. 启动可续传会话。向包含元数据（如有）的上传 URI 发出初始请求。
  2. 保存可续传会话 URI。保存初始请求的响应中返回的会话 URI；您将会在此会话的后续请求中用到此 URI。
  3. 上传文件。将媒体文件发送到可续传会话 URI。

此外，使用可续传上传的应用需要通过代码来恢复中断的上传。如果上传被中断，请查看已成功接收了多少数据量，然后从该中断处恢复上传。

注意：上传 URI 的有效期为一周。

第 1 步：启动可续传会话

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

此启动请求的正文不是为空就是仅包含元数据；您将在后续请求中传输要上传的文件的实际内容。

请在初始请求中使用以下 HTTP 标头：

  • X-Upload-Content-Type。将此项设为要在后续请求中传输的上传数据的媒体 MIME 类型。
  • X-Upload-Content-Length。将此项设为要在后续请求中传输的上传数据的字节数。 在发起此请求时，如果内容长度未知，那么您可以忽略此标头。
  • 如果提供元数据：Content-Type。根据元数据的数据类型进行设置。
  • Content-Length。将此项设为该初始请求的正文中提供的字节数。如果您采用的是分块传输编码，则不需要进行此操作。

请参阅 API 参考，了解每个方法接受的媒体 MIME 类型的列表以及上传文件的大小限制。

示例：可续传会话的启动请求

以下示例展示了如何针对 Gmail API 启动可续传会话。

POST /upload/gmail/v1/users/userId/messages/send?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: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

注意：对于不包含元数据的初始可续传更新请求，请将请求的正文留空，并将 Content-Length 标头设置为 0。

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

第 2 步：保存可续传会话 URI

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

示例：可续传会话的启动响应

下面是对第 1 步中的请求的响应：

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

请复制并保存该会话 URI，以便在后续请求中使用。

第 3 步：上传文件

如需上传文件，请向您在上一步中获得的上传 URI 发送 PUT 请求。上传请求的格式如下所示：

PUT session_uri

发出可续传文件上传请求时要使用的 HTTP 标头包含 Content-Length。请将此项设为您要在该请求中上传的字节数（通常为上传文件大小）。

示例：可续传文件上传请求

以下是为当前示例上传整个 2,000,000 字节电子邮件消息文件的可续传请求。

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

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

如果上传请求被中断，或者服务器返回了 HTTP 503 Service Unavailable 或任何其他 5xx 响应，请按照恢复中断的上传部分中列出的步骤进行操作。

分块上传文件

借助可续传上传，您可以将一个文件分成几块，然后发送一系列请求，按顺序上传每个分块。这并不是首选方法，因为发送更多请求会降低性能，所以我们一般不建议您这样做。不过，您可以使用分块来减少单个请求中传输的数据量。如果单个请求有固定的时间限制（例如某些类别的 Google App Engine 请求），那么该方法会非常实用。如果您使用的是默认不提供上传进度支持的旧版浏览器，该方法还可以让您提供上传进度指示。

恢复中断的上传

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

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

    注意：您不仅可以请求查询上传是否已被中断，还可以请求查询分块之间的状态。例如，如果您想为旧版浏览器显示上传进度指示，此请求会非常实用。

  2. 获取已上传的字节数。处理服务器针对状态查询返回的响应。服务器会在其响应中使用 Range 标头来表明目前已收到哪些字节。 例如，0-299999 的 Range 标头指示已收到文件的前 30 万个字节。
  3. 上传剩余的数据。最后，在您知道应从何处恢复请求后，请发送剩余的数据或当前分块。请注意，无论在何种情况下，您都需要将剩余的数据视为单独的分块。因此，在恢复上传时，您需要发送 Content-Range 标头。
示例：恢复中断的上传

1) 请求了解上传状态。

下面的请求使用 Content-Range 标头来指明 200 万字节文件中的当前位置未知。

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

注意：如果上传完毕，则状态响应可能为 201 Created 或 200 OK。如果在所有字节上传完毕后且客户端收到服务器返回的响应之前网络连接断开，则可能发生此情况。

3) 从中断处恢复上传。

下面的请求通过发送文件中的剩余字节（从第 43 个字节开始）来恢复上传。

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

bytes 43-1999999

最佳做法

在上传媒体时，了解错误处理方面的一些最佳做法很有帮助。

  • 恢复或重试由于连接中断或任何 5xx 错误而失败的上传，此类错误包括：
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • 如果在恢复或重试上传请求时收到任何 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 的值必须在每次等待后重新定义。

注意：等待时间始终是 (2 ^ n) 秒 + random_number_milliseconds 毫秒，其中 n 是单调递增的整数，初始值为 0。整数 n 在每次迭代（每次请求）后递增 1。

该算法设置为 n 等于 5 时终止。设置此上限的目的在于防止客户端无止尽地重试；在请求被视为“不可恢复的错误”之前，它使延迟总时间达到约 32 秒。重试更多次数是可以接受的，特别是在大数量上传正在进行的情况下；只需确保重试延迟时间的上限设置合理即可（比如说少于 1 分钟）。

API 客户端库指南