Google Photos mediaItems接口仅返回少量数据问题咨询

问题描述 #

我写了个脚本用来排查Google Photos里已上传和未上传的项目，昨天还能正常拉取8000+条数据，今天却只返回2张昨天拍的图；用Postman测试结果一样。删掉这两张图后，接口返回空列表但带nextPageToken，可我的图库明明有10000+张照片。

使用的CURL命令：

curl --location --request GET 'https://photoslibrary.googleapis.com/v1/mediaItems' \
--header 'Authorization: Bearer xxx'

返回结果：

{
    "nextPageToken": "xxxxxx"
}

疑惑点：是否存在标记最后一页的计数器？携带nextPageToken请求下一页仍返回空，求解答。

可能原因及解决办法 #

1. API分页机制的特殊情况 #

Google Photos API的分页逻辑中，nextPageToken并非严格只在有更多数据时返回——当服务器端的分页游标未完全同步（比如刚删除媒体项后），可能会出现空结果但带token的情况。此时继续请求下一页，大概率还是空数据，直到游标走到真正的末尾，才会停止返回nextPageToken。

2. 默认请求的隐性限制 #

• 默认排序与权限范围：mediaItems.list接口默认按媒体项的创建时间降序返回数据，如果旧数据没被返回，可能是令牌权限范围出了问题——比如重新获取的令牌仅申请了photoslibrary.readonly.appcreateddata（仅读取应用自建媒体），而非photoslibrary.readonly（读取所有媒体）。
• 显式指定pageSize：尝试在请求中添加pageSize参数（最大支持100），明确每页拉取数量，命令示例：

  curl --location --request GET 'https://photoslibrary.googleapis.com/v1/mediaItems?pageSize=100' \
  --header 'Authorization: Bearer xxx'
  

3. 令牌权限验证 #

检查当前Bearer令牌的权限范围，确保包含https://www.googleapis.com/auth/photoslibrary.readonly，如果权限不对，重新生成令牌时要勾选正确的权限选项。

4. API临时缓存或服务波动 #

这种空结果带token的情况，也可能是Google Photos API的临时缓存或服务波动导致的，可以等待一段时间后重试，或换个网络环境测试。

内容的提问来源于stack exchange，提问作者Rene Weteling