上传媒体

上传媒体内容包含两个步骤：

1. 使用上传端点将媒体文件的字节上传到 Google 服务器。此方法会返回可识别已上传字节的上传令牌。
2. 将上传令牌与 batchCreate 调用搭配使用，在用户的 Google 相册账号中创建媒体内容。

以下步骤概述了上传单个媒体内容的过程。如果您要上传多项媒体内容（很可能适用于任何生产应用），请查看上传最佳做法，以提高上传效率。

准备工作

所需的授权范围

将媒体内容上传到用户的媒体库或影集需要 photoslibrary.appendonly 范围。如需详细了解范围，请参阅授权范围。

接受的文件类型和大小

您可以上传此表格中列出的文件类型。

媒体类型	接受的文件类型	文件大小上限
照片	AVIF、BMP、GIF、HEIC、ICO、JPG、PNG、TIFF、WEBP、部分 RAW 文件。	200 MB
视频	3GP、3G2、ASF、AVI、DIVX、M2T、M2TS、M4V、MKV、MMV、MOD、MOV、MP4、MPG、MTS、TOD、WMV。	20 GB

第 1 步：上传字节

使用上传请求将字节上传到 Google。上传请求成功后，系统会返回原始文本字符串形式的上传令牌。使用这些上传令牌通过 batchCreate 调用创建媒体内容。

注意：通过 API 上传到 Google 相册的所有媒体内容均以完整分辨率和原始画质存储。如果每位用户的上传量超过 25MB，则您的应用应提醒用户，这些上传内容会占用其 Google 账号中的存储空间。

REST

在 POST 请求标头中添加以下字段：

标头字段
Content-type	设为 application/octet-stream。
X-Goog-Upload-Content-Type	推荐。请将此项设为您要上传的字节的 MIME 类型。 常见的 MIME 类型包括 image/jpeg、image/png 和 image/gif。
X-Goog-Upload-Protocol	设为 raw。

以下是 POST 请求标头：

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

在请求正文中包含文件的二进制文件：

media-binary-data

如果此 POST 请求成功，则返回原始文本字符串形式的上传令牌作为响应正文。如需创建媒体内容，请在 batchCreate 调用中使用这些文本字符串。

upload-token

建议上传文件大小小于 50 MB 的图片。超过 50 MB 的文件容易出现性能问题。

Google Photos Library API 支持可续传上传。借助断点续传，您可以将媒体文件拆分为多个部分，并一次上传一个部分。

第 2 步：创建媒体内容

上传媒体文件的字节后，您可以使用上传令牌在 Google 相册中将其创建为媒体内容。上传令牌在创建后的一天内有效。您必须始终将媒体内容添加到用户的媒体库，媒体内容只能添加到应用创建的影集。如需了解详情，请参阅授权范围。

如需创建新的媒体内容，请通过指定 newMediaItems 列表调用 mediaItems.batchCreate。每个 newMediaItem 都包含在 simpleMediaItem 中指定的上传令牌，以及向用户显示的可选说明。

说明字段不得超过 1,000 个字符，且应仅包含用户创建的有意义的文字。例如，“我们去公园”或“节日晚餐”。请勿添加文件名、程序化代码或其他自动生成的文字等元数据。

为达到最佳性能，请在一次调用中添加多项媒体内容，进而减少对 mediaItems.batchCreate 的调用次数。请务必等待上一个请求完成后，再为同一用户进行后续调用。

您可以指定说明内容和相应的上传令牌，进而在用户的媒体库中创建单项媒体内容或多项媒体内容：

REST

以下是 POST 请求标头：

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

请求正文应指定 newMediaItems 列表。

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

您还可以指定 albumId 和 albumPosition，以在影集中的特定位置插入媒体内容。

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

有关在影集中定位的详情，请参阅添加丰富内容。

警告：batchCreate 调用会将一次调用中创建的媒体内容数量限制为 50。此外，我们也不建议为同一用户并行调用多个 batchCreate。

内容创建响应

mediaItems.batchCreate 调用会返回您尝试创建的每项媒体内容的结果。newMediaItemResults 列表指示状态并包含请求的 uploadToken。非零状态代码表示存在错误。

REST

如果所有媒体内容均已成功创建，则请求将返回 HTTP 状态 200 OK。如果无法创建某些媒体内容，则请求将返回 HTTP 状态 207 MULTI-STATUS，表示部分内容创建成功。

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

如果成功添加了一项，则返回包含其 mediaItemId、productUrl 和 mediaMetadata 的 mediaItem。如需了解详情，请参阅访问媒体内容。

如果媒体内容为视频，则必须先对其进行处理。mediaItem 的 mediaMetadata 中包含 status，用于描述视频文件的处理状态。新上传的文件首先会返回 PROCESSING 状态，然后才能成为 READY 状态，以待使用。如需了解详情，请参阅访问媒体内容。

如果您在此次调用中遇到错误，请按照最佳做法进行操作，然后重试您的请求。您可能希望跟踪成功添加的内容，以便在下次请求期间将图片插入到影集中的正确位置。如需了解详情，请参阅创建影集。

返回结果的顺序始终与提交上传令牌的顺序相同。

注意：相同的媒体内容（定义为上传的相同字节）将被视为同一对象。这意味着系统将返回相同的媒体内容 id，即使它由不同的 uploadToken 引用。

上传内容的最佳实践

以下最佳实践和资源有助于提高上传内容的整体效率：

• 遵循重试和错误处理最佳实践，并注意以下几点：
  • 如果您的配额已用尽，或者因过快地进行过多调用而受到速率限制，则可能会出现 429 错误。请确保在前一个请求完成之前，不要为同一用户调用 batchCreate。
  • 429 错误需要至少延迟 30s 秒后才能重试。重试请求时，请使用指数退避算法策略。
  • 服务器遇到错误时会发生 500 错误。在上传时，这很可能是因为同时对同一用户进行了多次写入调用（如 batchCreate）。请检查请求的详细信息，并勿并行调用 batchCreate。
• 使用可续传上传流程可在网络中断时使上传更加稳健，让您能够恢复部分完成的上传，从而减少带宽用量。从客户端移动设备上传或上传大型文件时，这一点非常重要。

此外，请考虑在上传流程的每个步骤（上传字节和创建媒体内容）中参考以下提示。

上传字节

• 上传字节（以检索上传令牌）可以并行进行。
• 请务必在每次上传调用的 X-Goog-Upload-Content-Type 标头中设置正确的 MIME 类型。

创建媒体内容

• 请勿为单个用户并行调用 batchCreate。

  • 针对每位用户，依次（串行）调用 batchCreate。
  • 对于多名用户，请始终为每位用户依次进行 batchCreate 调用。仅并行为不同用户进行调用。

• 在对 batchCreate 的每次调用中添加尽可能多的 NewMediaItems，以最大限度地减少必须进行的调用总数。您最多可以添加 50 项。

• 设置由用户创建的有意义的说明文本。请勿在说明字段中添加元数据，例如文件名、程序化代码或其他自动生成的文本。

示例演示

此示例使用伪代码演示了如何为多位用户上传媒体内容。本指南旨在概述上传流程的两个步骤（上传原始字节和创建媒体内容），并详细介绍构建高效且弹性上传集成的最佳实践。

第 1 步：上传原始字节

首先，创建一个队列，用于上传所有用户的媒体内容的原始字节。跟踪每个用户返回的每个 uploadToken。请记住以下要点：

• 同时上传的线程数取决于您的操作环境。
• 根据需要考虑重新排列上传队列。例如，您可以根据每位用户剩余的上传次数、用户的总进度或其他要求来确定上传内容的优先级。

伪代码

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

第 2 步：创建媒体内容

在第 1 步中，您可以并行上传来自多个用户的多个字节，但在第 2 步中，您一次只能为每位用户发出一次调用。

伪代码

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

继续此过程，直到完成所有上传和媒体创建调用。