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

重要提示：在 2025 年 1 月 31 日 Apps 脚本关闭通讯录服务之前，请将脚本从通讯录服务迁移到 People API 高级服务。

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

本指南将帮助您了解哪些 Contacts 服务方法在 People API 高级服务中没有对等方法，了解您可以使用哪些替代方法，并找到用于迁移常见任务的代码示例。如需了解详情，请参阅 Contacts API 迁移指南。

没有 People API 等效方法的方法

以下列出了 Contacts 服务中没有相应方法可在 People API 高级服务中搜索联系人的 getContacts 方法。借助 People API 高级服务，您可以按来自 CONTACT 源的联系人的 names、nickNames、emailAddresses、phoneNumbers 和 organizations 字段进行搜索。

没有对应方法的方法

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 参数的 Contacts 服务中的 getContacts 方法。您可以使用 People API 高级服务中的 searchContacts 按等效字段获取联系人，但无法将搜索范围限定为特定标签。

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

People API 提供的其他功能

迁移到 People API 高级服务后，您可以访问以下 Contacts 服务中没有的 People API 功能：

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

常见任务的代码示例

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

按名称获取联系人群组

以下代码示例展示了如何按名称获取联系人群组，这相当于 Contacts 服务中的 getContactGroup(name)。

advanced/people.gs

在 GitHub 上查看

/**
 * 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);
  }
}

按电子邮件地址获取联系人

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

advanced/people.gs

在 GitHub 上查看

/**
 * 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()。

advanced/people.gs

在 GitHub 上查看

/**
 * 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);
  }
}

获取联系人的全名

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

advanced/people.gs

在 GitHub 上查看

/**
 * 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);
  }
}

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

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

advanced/people.gs

在 GitHub 上查看

/**
 * 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);
  }
}

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

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

advanced/people.gs

在 GitHub 上查看

/**
 * 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);
  }
}