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

重要事項：請在 Apps Script 2023 年 3 月停用聯絡人服務前，將指令碼從聯絡人服務遷移至 People API 進階服務。

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

本指南將說明哪些聯絡人服務方法在 People API 進階服務中沒有同等的功能、您可以改用哪些方法，以及尋找遷移一般工作的程式碼範例。詳情請參閱 Contacts API 遷移指南。

沒有 People API 對應項目的方法

以下列出聯絡人服務中的 getContacts 方法，的方法並未等同於在 People API 進階服務中搜尋聯絡人。透過 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 參數的 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);
  }
}