在Google Apps Script中操作People API的externalIds字段疑问

一、为什么访问thisResult.person.externalIDs[0]返回undefined？ #

你现在的searchContacts请求里readMask只指定了names，API只会返回你明确请求的字段，所以返回的person对象里没有externalIds（注意API字段名是小写s，你代码里写的externalIDs是大写D，这也是报错原因之一）。

修改请求的readMask，加上externalIds：

let found = People.People.searchContacts({
  "query": query,
  "readMask": "names,externalIds"
});

这样返回的person对象里才会包含externalIds数组，你才能正常访问对应元素。

二、修改/新增externalIds的示例代码 #

修改已有externalId #

确认数组存在后直接修改字段：

let thisResult = found.results[0];
// 假设要修改第一个externalId的值和类型
if (thisResult.person.externalIds && thisResult.person.externalIds.length > 0) {
  thisResult.person.externalIds[0].value = "new-external-id-value";
  thisResult.person.externalIds[0].type = "loginId"; // 使用预定义类型
}
// 调用更新接口，指定更新字段为externalIds
People.People.updateContact(thisResult.person, thisResult.person.resourceName, {updatePersonFields: "externalIds"});

新增externalId #

如果联系人没有externalIds，先初始化数组再添加：

let thisResult = found.results[0];
// 初始化数组（如果不存在）
if (!thisResult.person.externalIds) {
  thisResult.person.externalIds = [];
}
// 添加新的externalId
thisResult.person.externalIds.push({
  value: "new-custom-id",
  type: "custom", // 使用自定义类型
  customType: "员工编号" // 自定义类型名称
});
// 执行更新
People.People.updateContact(thisResult.person, thisResult.person.resourceName, {updatePersonFields: "externalIds"});

三、关于预定义类型（predefined types）的说明 #

externalId的type不是任意字符串，API有官方约定的可选值，比如account、customer、loginId、organization等，这些是统一的类型标识，用于规范数据格式。如果要使用自定义类型，必须把type设为"custom"，然后通过customType字段填写自定义的类型名称（比如"会员ID"、"项目编号"）。这和names里familyName可以自由输入的逻辑不同，是API对externalId字段的特定约束。

四、为什么不能有多个相同type的externalIds？ #

这是People API的内置校验规则，每个预定义类型在单个联系人下只能存在一个，目的是保证同类型标识的唯一性，避免数据混乱。如果需要添加多个同类别标识，比如不同系统的员工编号，应该使用"custom"类型，通过customType区分不同子类别（比如"员工编号-系统A"、"员工编号-系统B"）。

内容的提问来源于stack exchange，提问作者Robert M.