Google Apps Script中ContactsApp.getContact(email)迁移至People API的写法

前置准备 #

首先需要在你的 Apps Script 项目中启用 People API 服务：

• 打开项目编辑器，点击左侧侧边栏「服务」旁的「+」按钮
• 在服务列表中找到「People API」，选择v1版本后点击「添加」即可

等效实现代码 #

原有 ContactsApp.getContact(email) 功能可通过以下代码实现，行为与原方法基本一致，无匹配结果时返回null：

function getContactByEmail(targetEmail) {
  const searchOptions = {
    query: targetEmail,
    // 按需配置需要返回的联系人字段，多个字段用英文逗号分隔
    readMask: "names,emailAddresses,phoneNumbers,organizations,addresses",
    pageSize: 1
  }

  try {
    const searchResult = People.People.searchContacts(searchOptions);
    if (searchResult.results && searchResult.results.length > 0) {
      // 返回第一个匹配的联系人，和原ContactsApp逻辑一致
      return searchResult.results[0].person;
    }
    return null;
  } catch (err) {
    console.error("联系人查询失败：" + err.toString());
    return null;
  }
}

使用示例 #

// 调用示例，替换为你要查询的邮箱
const targetContact = getContactByEmail("xxx@example.com");
if (targetContact) {
  // 读取联系人姓名示例
  const contactName = targetContact.names?.[0]?.displayName;
  // 读取联系人手机号示例
  const contactPhone = targetContact.phoneNumbers?.[0]?.value;
}

补充说明 #

• 注意：readMask为必填参数，未明确指定需要返回的字段会触发接口报错
• 上述代码默认查询个人私人联系人库，如果你需要查询企业域的全局通讯录，可将搜索方法替换为 People.People.listDirectoryPeople，额外添加参数 sources: "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT" 即可
• 如果你需要返回所有匹配该邮箱的联系人，可将pageSize参数调整为更大的数值，最多支持100条

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