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

Google Apps 脚本已于 2022 年 12 月 16 日 弃用 Contacts 服务，并于 2025 年 1 月 31 日 关闭该服务。

请改用 People API 高级 服务。People API 使用较新的 JSON 协议，并提供高级功能，例如将联系人与个人资料合并。

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

没有 People API 等效方法的方法

以下列表列出了 Contacts 服务中的 getContacts 方法，这些方法在 People API 高级服务中没有等效的联系人搜索方法。借助 People 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)

下表列出了 Contacts 服务中使用了额外的 label 参数的 getContacts 方法。虽然 People API 高级 服务允许您使用 searchContacts按等效字段获取联系人， 但您无法将搜索范围限定为特定标签。

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

People API 提供的其他功能

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

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

常见任务的代码示例

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

按名称获取联系人组

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

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。

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

获取所有联系人

以下代码示例展示了如何获取用户的所有联系人，这相当于 Contacts 服务中的 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);
  }
}