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

Google Apps Script の Google コンタクトサービスは 2022 年 12 月 16 日 に非推奨となり、2025 年 1 月 31 日 にサービス提供を終了しました。

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

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

People API に相当するものがないメソッド

以下に、People API 拡張サービスで連絡先を検索する同等の方法がない、Google コンタクトサービスの getContacts メソッドを示します。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)`

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 パラメータを使用する Google コンタクトサービスの getContacts メソッドを示します。People API 拡張サービスでは、 searchContactsを使用して同等のフィールドで連絡先を取得できますが、検索を特定のラベルに限定することはできません。

部分的に相当するものがあるメソッド
`getContactsByEmailAddress(query, label)` `getContactsByName(query, label)` `getContactsByPhone(query, label)`

People API で利用できる追加機能

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

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

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

このセクションでは、Google コンタクトサービスの一般的なタスクについて説明します。コードサンプルは、People API 拡張サービスを使用してタスクを構築する方法を示しています。

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

次のコードサンプルは、名前で連絡先グループを取得する方法を示しています。これは、Google コンタクトサービスの getContactGroup に相当します。

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

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

次のコードサンプルは、メールアドレスで連絡先を取得する方法を示しています。これは、Google コンタクトサービスの getContact に相当します。

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

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

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

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

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

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

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

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

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

連絡先サービスから People API 高度なサービスに移行する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

People API に相当するものがないメソッド

People API で利用できる追加機能

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

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

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

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

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

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

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

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