如何使用Google Apps Script调用People API搜索谷歌联系人目录

当前代码报错核心原因 #

People.searchDirectoryPeople() 有两个必填参数未配置，仅设置查询关键词无法正常发起请求：

• 必须指定搜索来源为企业域目录
• 必须指定返回字段掩码（readMask）声明需要获取的用户信息字段

前置检查项 #

• 使用的必须是Google Workspace企业账号，个人谷歌账号没有企业目录权限，无法调用该接口
• 已经在Apps Script编辑器的「服务」中添加了People API服务
• 已经为脚本开启了目录只读权限，可在appsscript.json的oauthScopes字段中手动添加对应权限配置

可用实现代码 #

1. 按姓名检索目录 #

function searchByName() {
  // 搜索关键词：填入要检索的姓名
  const query = "Justin";
  // 构造请求
  const searchResults = People.People.searchDirectoryPeople({
    query: query,
    sources: [People.DirectorySourceTypes.DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE],
    readMask: "names,emailAddresses,phoneNumbers" // 按需指定需要返回的字段，多个用逗号分隔
  }, {
    pageSize: 20 // 单次返回最大结果数，最高支持100
  });

  // 处理返回结果
  const people = searchResults.people;
  if (people && people.length > 0) {
    people.forEach(person => {
      const name = person.names ? person.names[0].displayName : "无姓名信息";
      const email = person.emailAddresses ? person.emailAddresses[0].value : "无邮箱信息";
      console.log(`姓名：${name}，邮箱：${email}`);
    });
  } else {
    console.log("未找到匹配的目录用户");
  }
}

2. 按邮箱检索目录 #

仅需要把query参数替换为邮箱前缀或者完整邮箱即可，接口会自动匹配邮箱字段完成检索：

function searchByEmail() {
  // 搜索关键词：填入要检索的邮箱，支持前缀模糊匹配
  const query = "justin@yourdomain.com";
  const searchResults = People.People.searchDirectoryPeople({
    query: query,
    sources: [People.DirectorySourceTypes.DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE],
    readMask: "names,emailAddresses,phoneNumbers"
  }, {
    pageSize: 20
  });

  // 结果处理逻辑和按姓名搜索完全一致
  const people = searchResults.people;
  if (people && people.length > 0) {
    people.forEach(person => {
      const name = person.names ? person.names[0].displayName : "无姓名信息";
      const email = person.emailAddresses ? person.emailAddresses[0].value : "无邮箱信息";
      console.log(`姓名：${name}，邮箱：${email}`);
    });
  } else {
    console.log("未找到匹配的目录用户");
  }
}

常见问题排查 #

• 返回权限错误：检查appsscript.json中是否添加了目录只读权限，重新运行脚本触发授权流程
• 返回无结果：确认搜索关键词正确，且该用户确实在你的企业域目录中
• 接口报错403：确认你的Workspace管理员没有限制普通用户访问目录权限

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