連絡先サービスから People API 高度なサービスに移行する

重要: 2025 年 1 月 31 日に Apps Script で Google コンタクト サービスが廃止される前に、スクリプトを Google コンタクト サービスから People API 拡張サービスに移行してください。

Apps Script では、2022 年 12 月 16 日に連絡先サービスが非推奨になりました。代わりに、People API の高度なサービスを使用してください。People API ではより新しい JSON プロトコルが使用されており、連絡先とプロフィールの統合といった高度な機能が備わっております。

このガイドでは、People API の高度なサービスに相当するメソッドがない Contacts サービス メソッド、代わりに使用できるメソッド、一般的なタスクを移行するためのコードサンプルについて説明します。詳しくは、Contacts API 移行ガイドを参照してください。

People API に同等のメソッドがないメソッド

以下に、People API の高度なサービスで連絡先を検索する同等の方法がない、連絡先サービスの getContacts メソッドを一覧表示します。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 パラメータを使用する Contacts サービスの getContacts メソッドを示します。People API の高度なサービスから searchContacts を使用して、同等のフィールドで連絡先を取得できますが、検索を特定のラベルに制限することはできません。

部分的に同等のメソッド
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

People API で利用できるその他の機能

People API 拡張サービスに移行すると、Google コンタクト サービスでは利用できない次の People API 機能にアクセスできます。

• データソースを指定する - 人物に関する情報を検索する際に、検索対象（Google コンタクトや Google プロフィールなど）を指定できます。
• クエリ文字列でユーザーを検索する - 特定の文字列に一致するプロフィールと連絡先のリストを取得できます。
• バッチ リクエスト - People API 呼び出しをバッチ処理して、スクリプトの実行時間を短縮できます。

一般的なタスクのコードサンプル

このセクションでは、連絡先サービスの一般的なタスクを一覧表示します。コードサンプルは、People API の高度なサービスを使用してタスクを構築する方法を示しています。

名前で連絡先グループを取得する

次のコードサンプルは、名前で連絡先グループを取得する方法を示しています。これは、連絡先サービスの 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);
  }
}

すべての連絡先を取得する

次のコードサンプルは、ユーザーのすべての連絡先を取得する方法を示しています。これは、連絡先サービスの 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);
  }
}

連絡先のすべての電話番号を取得する

次のコードサンプルは、連絡先のすべての電話番号を取得する方法を示しています。これは、連絡先サービスの 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);
  }
}

連絡先の特定の電話番号を取得する

次のコードサンプルは、連絡先の特定の電話番号を取得する方法を示しています。これは、連絡先サービスの 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);
  }
}