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

重要提示：请将您的脚本从通讯录服务迁移到 People API （在 Apps 脚本于 3 月份关闭通讯录服务前） 2023 年。

Apps 脚本已于 2022 年 12 月 16 日弃用通讯录服务。相反， 使用 People API 高级服务。People API 使用 一种较新的 JSON 协议 例如合并联系人和个人资料等高级功能

使用本指南了解哪些通讯录服务方法在 People API 高级服务，了解您可以改用的功能，并查找代码 迁移常见任务的示例。如需了解详情，请参阅 Contacts API 迁移指南。

没有 People API 等效方法的方法

下面列出了通讯录服务中不会getContacts 拥有 在 People API 高级服务中以同等方式搜索联系人。包含 联系人 API 高级服务，您可以按联系人的 names 进行搜索， nickNames、emailAddresses、phoneNumbers和organizations字段 来自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)

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

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

People API 提供的其他功能

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

• 指定数据源：搜索用户的相关信息时，您可以指定在何处搜索 例如 Google 联系人或 Google 个人资料。
• 按查询字符串搜索用户 - 您可以获取与特定字符串匹配的个人资料和联系人列表。
• 批量请求 - 您可以 People API 调用有助于缩短脚本执行时间。

常见任务的代码示例

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

按名称获取联系人群组

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

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

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

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

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

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

获取联系人的全名

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

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

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

以下代码示例展示了如何获取某个 contact，它相当于通讯录服务中的 getPhones()。

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

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

以下代码示例显示了如何获取某个 contact，它相当于通讯录服务中的 getPhoneNumber()。

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