为何给Google Drive文件添加元数据时，元数据被写入文件内容？

问题场景 #

尝试为Google Drive中已上传的文本文件添加标题、描述等元数据，但发送请求后，文件名称等属性未发生变化，元数据反而被写入到文件内容中，例如文件内出现title=name...的内容。

你的代码 #

$.ajax({
  url: "https://www.googleapis.com/upload/drive/v2/files/---?UploadType=multipart",
  data: {
    title: "name...",
    // other parameters indicated by google
  },
  headers: {
    "Authorization": "Bearer ..."
  },
  contentType: "application/json", //as indicated by google
  type: "PUT",
  success: function () {
    // ...
  }
});

问题原因 #

1. 请求类型误用：使用UploadType=multipart时，需要构造包含元数据和文件内容的多部分请求，但当前代码直接将元数据以表单格式发送，导致Google Drive将其识别为文件内容而非元数据。
2. 内容格式不匹配：设置contentType: "application/json"，但data却是普通对象（会被jQuery转换为表单格式），请求格式与声明的Content-Type不匹配，进一步导致解析错误。

解决方案 #

方案1：仅更新元数据（不修改文件内容） #

如果只需修改文件属性（标题、描述等），无需上传文件内容，直接使用普通PUT请求，移除UploadType=multipart参数：

$.ajax({
  url: "https://www.googleapis.com/drive/v2/files/---",
  data: JSON.stringify({
    title: "新文件标题",
    description: "文件描述信息"
    // 其他需要更新的元数据字段
  }),
  headers: {
    "Authorization": "Bearer ...",
    "Content-Type": "application/json"
  },
  type: "PUT",
  success: function (res) {
    console.log("元数据更新成功", res);
  },
  error: function (err) {
    console.error("更新失败", err);
  }
});

方案2：同时更新元数据和文件内容 #

若需要同时修改元数据和文件内容，必须正确构造multipart请求，使用FormData对象分隔元数据与文件内容：

const formData = new FormData();

// 添加元数据部分
const metadataBlob = new Blob(
  [JSON.stringify({ title: "新标题", description: "新描述" })],
  { type: "application/json" }
);
formData.append("metadata", metadataBlob);

// 添加文件内容部分（替换为你需要的文本内容）
const contentBlob = new Blob(["文件的新文本内容"], { type: "text/plain" });
formData.append("file", contentBlob);

$.ajax({
  url: "https://www.googleapis.com/upload/drive/v2/files/---?uploadType=multipart",
  data: formData,
  headers: {
    "Authorization": "Bearer ..."
  },
  contentType: false, // 让jQuery自动处理多部分请求的Content-Type
  processData: false, // 禁止jQuery处理FormData
  type: "PUT",
  success: function (res) {
    console.log("更新成功", res);
  },
  error: function (err) {
    console.error("更新失败", err);
  }
});

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