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

重要事項：請在 2025 年 1 月 31 日前，將指令碼從 Contacts 服務遷移至 People API 進階服務，因為 Apps Script 將於當天停用 Contacts 服務。

Apps Script 已於 2022 年 12 月 16 日淘汰 Contacts 服務。請改用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 進階服務後，您就能存取下列 People API 功能，這些功能在聯絡人服務中無法使用：

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

常見工作的程式碼範例

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

依名稱取得聯絡人群組

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

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

依電子郵件地址取得聯絡人

下列程式碼範例顯示如何依電子郵件地址取得聯絡人，這相當於聯絡人服務中的 getContact(emailAddress)。

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

取得聯絡人的全名

下列程式碼範例說明如何取得聯絡人的全名，這相當於聯絡人服務中的 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);
  }
}

取得聯絡人的所有電話號碼

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