调用Google Photos API PATCH更新mediaItem描述返回400错误

问题现象 #

调用PATCH接口更新Google Photos媒体库中mediaItem的description字段时收到400错误，操作参考官方开发文档中修改媒体项描述的相关指引。项目基于Google Apps Script开发，其他API调用（列出相册、获取相册内mediaItem列表等）均可正常执行，已配置的权限范围：

https://www.googleapis.com/auth/photoslibrary.readonly https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata

原实现代码：

// thisMediaItem 是之前接口调用返回的媒体项对象
var id = thisMediaItem.id;
Logger.log("Here is the full JSON for the media item " + id);
Logger.log(JSON.stringify(thisMediaItem));

// 尝试发起PATCH请求更新媒体项描述
var url = 'https://photoslibrary.googleapis.com/v1/mediaItems/' + id + "?updateMask=description";
var response = UrlFetchApp.fetch(url, {
  headers: { Authorization: 'Bearer ' + photoService.getAccessToken() },
  muteHttpExceptions: true,
  method: "patch",
  payload: { "description": "my new description" }
});
Logger.log(response.getContentText());

运行后返回description字段不存在的错误，即使请求payload中已传入该字段、移除字段名引号后问题仍未解决，错误日志核心内容：

{
  "error": {
    "code": 400,
    "message": "Invalid JSON payload received. Unknown name \"description\": Cannot bind query parameter. Field 'description' could not be found in request message.",
    "status": "INVALID_ARGUMENT"
  }
}

问题原因 #

• 核心原因：UrlFetchApp.fetch默认将payload以application/x-www-form-urlencoded表单格式发送，而Google Photos PATCH接口要求请求体为application/json格式，未指定Content-Type时服务端会把传入的字段当成URL查询参数解析，自然无法识别请求体中的description字段。
• 额外注意：已配置的photoslibrary.edit.appcreateddata权限仅允许修改当前应用自身创建的媒体项，如果目标媒体项是手动上传、或由其他应用创建，就算请求格式修正后也会返回权限错误。

修正代码 #

请求时明确指定Content-Type为JSON，同时将payload对象序列化为JSON字符串再发送：

var url = 'https://photoslibrary.googleapis.com/v1/mediaItems/' + id + "?updateMask=description";
var response = UrlFetchApp.fetch(url, {
  headers: { 
    Authorization: 'Bearer ' + photoService.getAccessToken(),
    'Content-Type': 'application/json'
  },
  muteHttpExceptions: true,
  method: "patch",
  payload: JSON.stringify({ "description": "my new description" })
});

内容的提问来源于stack exchange，提问作者Mark Lamprecht