如何用Google Apps Script通过Google People API获取并去重添加联系人

一、获取包含姓名、手机号的联系人列表 #

使用People API的People.People.connections.list方法拉取联系人，需明确指定需要返回的字段（姓名、手机号），以下是完整代码示例：

function getContactsList() {
  // 配置请求参数：拉取当前用户联系人，指定返回姓名和手机号字段
  const params = {
    resourceName: 'people/me',
    personFields: 'names,phoneNumbers',
    pageSize: 100 // 可根据联系人数量调整，最大支持1000
  };

  let contacts = [];
  let response = People.People.connections.list(params);
  
  // 处理分页结果（联系人数量超过pageSize时需循环拉取）
  while (response.connections) {
    response.connections.forEach(contact => {
      // 提取姓名（优先取显示名称）
      const name = contact.names ? contact.names[0].displayName : '无姓名';
      // 提取所有手机号
      const phones = contact.phoneNumbers ? contact.phoneNumbers.map(phone => phone.value) : [];
      
      contacts.push({
        name: name,
        phoneNumbers: phones
      });
    });

    // 检查是否有下一页数据
    if (response.nextPageToken) {
      params.pageToken = response.nextPageToken;
      response = People.People.connections.list(params);
    } else {
      break;
    }
  }

  console.log(contacts);
  return contacts;
}

关键注意点： #

• personFields必须明确声明所需字段，API不会返回未指定的字段，这是容易遗漏的环节
• 必须处理分页逻辑，否则只能拉取pageSize数量以内的联系人
• 部分联系人可能缺失姓名或手机号，需做空值容错处理

二、添加新联系人并避免重复 #

核心逻辑是先通过唯一标识（建议用手机号，姓名易重复）检查联系人是否存在，不存在则调用API创建。以下是实现代码：

// 辅助函数：通过手机号快速检查联系人是否存在
function isContactExists(phoneNumber) {
  const response = People.People.searchContacts({
    query: phoneNumber,
    readMask: 'phoneNumbers'
  });
  return response.results && response.results.length > 0;
}

// 添加新联系人函数
function addNewContact(name, phoneNumber) {
  // 先校验重复
  if (isContactExists(phoneNumber)) {
    console.log(`手机号 ${phoneNumber} 对应的联系人已存在`);
    return;
  }

  // 构造符合API要求的联系人数据结构
  const contactData = {
    names: [
      {
        givenName: name.split(' ')[0], // 拆分名
        familyName: name.split(' ').slice(1).join(' ') // 拆分姓（支持姓名带空格的情况）
      }
    ],
    phoneNumbers: [
      {
        value: phoneNumber,
        type: 'mobile' // 可指定类型：home、work等
      }
    ]
  };

  // 调用API创建联系人
  const createdContact = People.People.createContact(contactData);
  console.log(`联系人 ${name} 添加成功，ID：${createdContact.resourceName}`);
  return createdContact;
}

// 调用示例：添加名为"张三"、手机号"13800138000"的联系人
// addNewContact("张三", "13800138000");

关键注意点： #

• 用searchContacts直接搜索手机号比遍历所有联系人效率更高，适合联系人较多的场景
• createContact的参数结构必须严格遵循API规范，names和phoneNumbers都是数组格式，每个元素需包含指定字段
• 确认脚本已授权https://www.googleapis.com/auth/contacts权限，可在脚本编辑器「项目设置」→「OAuth 同意屏幕」中检查权限范围

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