コンタクト サービスから People API の高度なサービスに移行する

重要: 2023 年 3 月に Apps Script がコンタクト サービスを廃止する前に、連絡先サービスから People API 詳細サービスにスクリプトを移行してください。

Apps Script のコンタクト サービスは 2022 年 12 月 16 日に非推奨となりました。代わりに、People API Advanced Service を使用してください。People API は新しい JSON プロトコルを使用しており、連絡先とプロファイルのマージなどの高度な機能を備えています。

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

同等の People API を使用しないメソッド

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

部分的同等物を含むメソッド
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

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

People API 詳細サービスに移行すると、連絡先サービスでは使用できない次の 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);
  }
}

連絡先の氏名を取得する

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