如何为Google Contacts新增增删改触发事件实现与Google Sheets同步

原生触发支持情况 #

Google Apps Script及Google People API当前没有提供类似Calendar API的onContactUpdated原生事件触发器，官方并未开放联系人变更的主动推送触发能力，你查询到的信息无误，不存在遗漏的官方文档说明。

低配额替代实现方案 #

无需全量轮询，使用People API提供的syncToken增量同步机制配合低频率时间触发器即可满足需求，不会超出每日运行时长配额：

方案核心逻辑 #

• 首次同步时全量拉取所有联系人数据写入表格，同时获取并存储接口返回的syncToken（用于标记当前同步的时间节点）
• 后续每次同步仅需携带已存储的syncToken调用接口，接口只会返回该时间节点之后发生增、删、改的增量联系人数据，无需拉取全量数据
• 处理完增量数据后更新存储的syncToken即可

配额消耗说明 #

单趟增量同步执行时长通常不超过3秒，即使设置每10分钟触发一次，单日总运行时长也仅为 3624=432秒（约7分钟），远低于每日90分钟的配额上限，就算后续联系人规模增长到数千条也不会有超额风险。

参考实现代码 #

// 首次全量同步执行一次即可
function firstFullSync() {
  const properties = PropertiesService.getScriptProperties();
  const response = People.People.Connections.list('people/me', {
    personFields: 'names,emailAddresses,phoneNumbers',
    pageSize: 1000
  });
  // 全量写入表格的逻辑自行实现
  writeContactsToSheet(response.connections);
  // 存储syncToken
  properties.setProperty('contactSyncToken', response.nextSyncToken);
}

// 增量同步函数，绑定到时间触发器
function incrementalSyncContacts() {
  const properties = PropertiesService.getScriptProperties();
  const syncToken = properties.getProperty('contactSyncToken');
  if (!syncToken) {
    firstFullSync();
    return;
  }
  try {
    const response = People.People.Connections.list('people/me', {
      personFields: 'names,emailAddresses,phoneNumbers',
      syncToken: syncToken,
      pageSize: 1000
    });
    // 处理增量数据的逻辑自行实现：新增/更新/删除对应表格行
    processDeltaContacts(response.connections);
    // 更新syncToken
    if (response.nextSyncToken) {
      properties.setProperty('contactSyncToken', response.nextSyncToken);
    }
  } catch (e) {
    // 如果syncToken过期失效，重新执行全量同步
    if (e.message.includes('Sync token is invalid or expired')) {
      firstFullSync();
    }
  }
}

// 绑定触发器的代码，执行一次即可创建10分钟间隔的触发器
function createSyncTrigger() {
  ScriptApp.newTrigger('incrementalSyncContacts')
    .timeBased()
    .everyMinutes(10)
    .create();
}

注意事项 #

• 使用前需要在Apps Script编辑器的「服务」中添加「People API」服务
• 你可以根据自己对同步实时性的要求调整触发间隔，最短可以设置为每分钟触发一次，仍不会超出配额限制

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