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

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

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

このガイドでは、Contacts サービス メソッドのうち、People API アドバンスト サービスに同等のメソッドがないメソッドについて説明します。また、代わりに使用できるメソッドと、一般的なタスクの移行に使用できるコードサンプルについても説明します。詳しくは、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 呼び出しをバッチ処理すると、スクリプトの実行時間を短縮できます。

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

このセクションでは、Contacts サービスの一般的なタスクについて説明します。コードサンプルは、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);
  }
}

メールアドレスで連絡先を取得する

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

連絡先のフルネームを取得する

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

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

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