上传媒体内容的过程分为两个步骤：
- 使用上传端点将媒体文件的字节上传到 Google 服务器。此方法会返回可识别已上传字节的上传令牌。
- 使用带有上传令牌的 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 调用创建媒体内容。
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 相册中将其创建为媒体内容。上传令牌有效 创建后一天内有效。媒体项始终会添加到用户的 库。媒体内容只能添加到 的影集 应用。有关详情，请参阅授权 范围。
要创建新的媒体项，请调用
mediaItems.batchCreate
方法是指定 newMediaItems 列表。每个 newMediaItem 均包含一个上传内容
simpleMediaItem 中指定的令牌，以及可选的说明
向用户显示的信息
说明字段不得超过 1000 个字符，且只能包含 用户创建的有意义文本。例如，“我们的公园之旅”或 “节日晚餐”。请勿包含元数据，例如文件名、程序化交易 标记或其他自动生成的文本。
为了获得最佳效果，请将来电次数减少至 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"
}
}
有关在相册中定位的详情，请参阅添加 扩充项。
内容创建响应
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"
}
}
]
}
如果成功添加项，系统将返回 mediaItem，其中包含其
mediaItemId、productUrl和mediaMetadata。如需了解详情，请参阅
访问媒体内容。
如果媒体内容是视频，则必须先对其进行处理。mediaItem
mediaMetadata 中包含一个 status，用于描述处理过程
视频文件的状态。新上传的文件会返回 PROCESSING 状态
，然后再设为 READY，以供使用。有关详情，请参阅访问媒体
内容。
如果您在此次通话中遇到错误，请按照最佳 做法并重试您的请求。您 可能希望跟踪成功添加的内容， 发送到相册中的正确位置。有关 请参阅创建 影集。
返回结果的顺序始终与上传令牌的顺序相同 提交。
上传的最佳做法
以下最佳做法和资源有助于提高您的整体效率 ：
- 遵循重试和错误处理最佳实践，并注意以下几点：
- 使用可续传上传流程执行以下操作： 让你的上传在出现网络中断时更稳健 恢复部分完成的上传，从而减少带宽用量。从客户端移动设备上传或上传大型文件时，这一点非常重要。
此外，请考虑在上传流程的每个步骤（上传字节和创建媒体内容）中参考以下提示。
上传字节
- 上传字节（以检索上传令牌）可以并行执行。
- 请务必为每次上传调用在
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.
继续此过程，直到完成所有上传和媒体创建调用。