从通讯录服务迁移到 People API 高级服务

重要提示:Apps 脚本将于 2023 年 3 月关闭通讯录服务,在此之前,请将脚本从“通讯录”服务迁移到 People API 高级服务。

Apps 脚本已于 2022 年 12 月 16 日弃用通讯录服务。请改用 People API 高级服务。People API 使用较新的 JSON 协议并提供高级功能,例如将联系人与个人资料合并。

通过本指南,您可以了解哪些通讯录服务方法在 People API 高级服务中没有对应项,了解您可以改用哪些方法,并查找用于迁移常见任务的代码示例。如需了解详情,请参阅 Contacts API 迁移指南

没有 People API 等效项的方法

下面列出了通讯录服务中与在 People API 高级服务中搜索联系人不具有相同方法的 getContacts 方法。借助 People API 高级服务,您可以按联系人的 namesnickNamesemailAddressesphoneNumbersorganizations 字段(来自 CONTACT 来源)进行搜索。

没有等效项的方法
  • getContactsByAddress(query)
  • getContactsByAddress(query, label)
  • getContactsByAddress(query, label)
  • getContactsByCustomField(query, label)
  • getContactsByDate(month, day, label)
  • getContactsByDate(month, day, year, label)
  • getContactsByDate(month, day, year, label)
  • getContactsByIM(query)
  • getContactsByIM(query, label)
  • getContactsByJobTitle(query)
  • getContactsByNotes(query)
  • getContactsByUrl(query)
  • getContactsByUrl(query, label)
  • getContactsByGroup(group)

下面列出了通讯录服务中使用额外的 label 参数的 getContacts 方法。您可以使用 People API 高级服务中的 searchContacts 按等效字段获取联系人,但无法将搜索范围限制为特定标签。

具有部分等效项的方法
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

People API 提供的其他功能

迁移到 People API 高级服务时,您可以访问通讯录服务中不可用的以下 People API 功能:

  • 指定数据源 - 搜索某人的信息时,可以指定搜索位置,例如 Google 联系人或 Google 个人资料。
  • 按查询字符串搜索人员 - 您可以获取与特定字符串匹配的个人资料和联系人列表。
  • 批量请求 - 您可以批量处理 People API 调用,以帮助缩短脚本执行时间。

常见任务的代码示例

本部分列出了通讯录服务中的常见任务。这些代码示例展示了如何使用 People API 高级服务构建任务。

按名称获取联系人群组

以下代码示例演示了如何按名称获取联系人组,这相当于通讯录服务中的 getContactGroup(name)

高级/people.gs
/**
 * Gets a contact group with the given name
 * @param {string} name The group name.
 * @see https://developers.google.com/people/api/rest/v1/contactGroups/list
 */
function getContactGroup(name) {
  try {
    const people = People.ContactGroups.list();
    // Finds the contact group for the person where the name matches.
    const group = people['contactGroups'].find((group) => group['name'] === name);
    // Prints the contact group
    console.log('Group: %s', JSON.stringify(group, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the contact group with an error %s', err.message);
  }
}

通过电子邮件地址获取联系人

以下代码示例演示了如何通过电子邮件地址获取联系人,这相当于通讯录服务中的 getContact(emailAddress)

高级/people.gs
/**
 * Gets a contact by the email address.
 * @param {string} email The email address.
 * @see https://developers.google.com/people/api/rest/v1/people.connections/list
 */
function getContactByEmail(email) {
  try {
    // Gets the person with that email address by iterating over all contacts.
    const people = People.People.Connections.list('people/me', {
      personFields: 'names,emailAddresses'
    });
    const contact = people['connections'].find((connection) => {
      return connection['emailAddresses'].some((emailAddress) => emailAddress['value'] === email);
    });
    // Prints the contact.
    console.log('Contact: %s', JSON.stringify(contact, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

获取所有联系人

以下代码示例展示了如何获取用户的所有联系人,这相当于通讯录服务中的 getContacts()

高级/people.gs
/**
 * Gets a list of people in the user's contacts.
 * @see https://developers.google.com/people/api/rest/v1/people.connections/list
 */
function getConnections() {
  try {
    // Get the list of connections/contacts of user's profile
    const people = People.People.Connections.list('people/me', {
      personFields: 'names,emailAddresses'
    });
    // Print the connections/contacts
    console.log('Connections: %s', JSON.stringify(people, null, 2));
  } catch (err) {
    // TODO (developers) - Handle exception here
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

获取联系人的全名

以下代码示例展示了如何获取联系人的全名,这相当于通讯录服务中的 getFullName()

高级/people.gs
/**
 * Gets the full name (given name and last name) of the contact as a string.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getFullName() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'names'});
    // Prints the full name (given name + family name)
    console.log(`${people['names'][0]['givenName']} ${people['names'][0]['familyName']}`);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

获取联系人的所有电话号码

以下代码示例展示了如何获取联系人的所有电话号码,这相当于通讯录服务中的 getPhones()

高级/people.gs
/**
 * Gets all the phone numbers for this contact.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getPhoneNumbers() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'phoneNumbers'});
    // Prints the phone numbers.
    console.log(people['phoneNumbers']);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}

获取联系人的特定电话号码

以下代码示例展示了如何获取联系人的特定电话号码,这相当于通讯录服务中的 getPhoneNumber()

高级/people.gs
/**
 * Gets a phone number by type, such as work or home.
 * @see https://developers.google.com/people/api/rest/v1/people/get
 */
function getPhone() {
  try {
    // Gets the person by specifying resource name/account ID
    // in the first parameter of People.People.get.
    // This example gets the person for the user running the script.
    const people = People.People.get('people/me', {personFields: 'phoneNumbers'});
    // Gets phone number by type, such as home or work.
    const phoneNumber = people['phoneNumbers'].find((phone) => phone['type'] === 'home')['value'];
    // Prints the phone numbers.
    console.log(phoneNumber);
  } catch (err) {
    // TODO (developers) - Handle exception
    console.log('Failed to get the connection with an error %s', err.message);
  }
}