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

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

您可以透過本指南瞭解哪些聯絡人服務方法在 People API 進階服務中沒有對應項目，瞭解可替代的選項，以及找出用於遷移常見工作內容的程式碼範例。詳情請參閱 Contacts API 遷移指南。

沒有 People API 對應項目的方法

下表列出聯絡人服務中的 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)

以下列出使用額外 label 參數的聯絡人服務 getContacts 方法。您可以使用 People API 進階服務的 searchContacts，根據等效欄位取得聯絡人，但無法將搜尋範圍限制在特定標籤。

部分對等方法
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

People API 提供的其他功能

遷移至 People API 進階服務後，您可以存取下列 People API 功能，這些功能在 Contacts 服務中無法使用：

  • 指定資料來源：搜尋某人相關資訊時，您可以指定搜尋位置，例如 Google 聯絡人或 Google 個人資料。
  • 根據查詢字串搜尋使用者：您可以取得符合特定字串的個人資料和聯絡人清單。
  • 批次要求：您可以批次處理 People API 呼叫，以縮短指令碼執行時間。

常見工作的程式碼範例

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

依名稱取得聯絡人群組

以下程式碼範例顯示如何根據聯絡人群組名稱取得該群組，這相當於聯絡人服務中的 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);
  }
}

取得所有聯絡人

以下程式碼範例說明如何取得使用者的所有聯絡人，這相當於聯絡人服務中的 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);
  }
}