Google Apps Script中People API searchContacts()用法及结果不全问题求助

一、People.People.searchContacts() 正确用法 #

1. 搜索查询语句正确写法 #

People API的searchContacts接口不支持类SQL的条件过滤语法，query参数直接传入纯文本搜索关键词即可，接口会自动匹配联系人姓名、电话、邮箱、地址等字段的子串内容。比如要搜索包含5632的手机号，直接传"5632"作为query值即可，不需要写字段过滤规则。

2. readMask正确配置格式 #

readMask为逗号分隔的联系人字段列表，直接填写你需要返回的字段名即可，多个字段用英文逗号分隔，不要加空格。示例配置：names,phoneNumbers,addresses,emailAddresses，只要是People资源支持的字段都可添加。

基础调用示例 #

function searchContactSample() {
  // 直接传入要搜索的关键词
  const searchQuery = "5632";
  const searchResp = People.People.searchContacts({
    query: searchQuery,
    readMask: "names,phoneNumbers,addresses,emailAddresses",
    // 单页返回数量拉满，接口最大支持100
    pageSize: 100
  });

  // 后续处理逻辑
  if (searchResp.results) {
    const personBob = searchResp.results.find(res => 
      res.person.names?.[0]?.displayName.includes("Bob Q22222")
    );
    console.log(personBob);
  }
}

二、搜索结果不全的原因及解决方案 #

常见原因 #

• 默认返回数量限制：接口默认pageSize为25，仅返回第一页匹配结果，未处理分页的情况下会遗漏后续页结果
• 未指定完整数据源：默认仅搜索Google联系人源，如果你有设备同步、其他账号同步的联系人，需要指定mergeSources参数
• 老Contacts API创建的联系人索引未同步：旧接口创建的联系人未被纳入People API的搜索索引，导致匹配结果缺失
• 缓存预热时间不足：官方建议的5秒预热仅适用于联系人数量较少的场景，1万+联系人需要更长预热时间

对应解决方案 #

1. 开启分页查询，拉取所有匹配结果
2. 补充mergeSources参数，覆盖所有联系人源
3. 全量拉取一次联系人列表触发索引重建
4. 延长缓存预热时间到15秒以上

修正后的完整代码示例 #

function fullSearchContact() {
  // 1. 缓存预热，空查询触发索引加载
  People.People.searchContacts({
    query: "",
    readMask: "names",
    pageSize: 1
  });
  // 1万+联系人建议预热15秒
  Utilities.sleep(15000);

  const targetQuery = "Q12755";
  const allResults = [];
  let nextPageToken = null;

  do {
    const searchParams = {
      query: targetQuery,
      readMask: "names,addresses,emailAddresses,phoneNumbers",
      pageSize: 100,
      // 指定所有支持的联系人源
      mergeSources: ["GOOGLE_CONTACTS", "DEVICE_CONTACT"],
      pageToken: nextPageToken
    };
    const currentPage = People.People.searchContacts(searchParams);
    if (currentPage.results) {
      allResults.push(...currentPage.results);
    }
    nextPageToken = currentPage.nextPageToken;
  } while (nextPageToken);

  // 输出所有匹配结果
  if (allResults.length > 0) {
    allResults.forEach((res, index) => {
      Logger.log(`结果${index + 1}: ${res.person.names[0].displayName}`);
    });
  } else {
    Logger.log(`无匹配${targetQuery}的结果`);
  }
}

附加修复方案（针对老Contacts API创建的联系人） #

如果上述代码仍有结果缺失，先运行一次全量联系人拉取脚本触发索引重建，完成后再执行搜索即可：

function rebuildContactIndex() {
  let nextPageToken = null;
  do {
    People.People.Connections.list("people/me", {
      personFields: "names",
      pageSize: 100,
      pageToken: nextPageToken
    });
    nextPageToken = conn.nextPageToken;
    // 无需处理返回结果，拉取动作即可触发索引同步
  } while (nextPageToken);
  Logger.log("索引重建完成");
}

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