從聯絡人服務遷移至 People API 進階服務

Apps Script 已於 2022 年 12 月 16 日淘汰聯絡人服務。請改用People API 進階服務。People API 使用較新的 JSON 通訊協定，並提供進階功能，例如將聯絡人與設定檔合併。

本指南將說明哪些聯絡人服務方法在 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 呼叫，縮短指令碼執行時間。

常見工作的程式碼範例

本節列出聯絡人服務的常見工作。程式碼範例說明如何使用 People API 進階服務建構工作。

依名稱取得聯絡人群組

下列程式碼範例說明如何依名稱取得聯絡人群組，這相當於 Contacts 服務中的 getContactGroup(name)。

advanced/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)。

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

取得所有聯絡人

以下程式碼範例說明如何取得使用者的所有聯絡人，這相當於 Contacts 服務中的 getContacts()。

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

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

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

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