Переход со службы «Контакты» на расширенную службу People API

Apps Script объявил службу «Контакты» устаревшей 16 декабря 2022 года . Вместо этого используйте расширенный сервис People API . People API использует более новый протокол JSON и предоставляет расширенные функции, такие как объединение контактов с профилями.

Используйте это руководство, чтобы узнать, какие методы службы «Контакты» не имеют аналогов в расширенной службе API «People», узнать, что можно использовать вместо них, и найти примеры кода для миграции распространённых задач. Подробнее см. в Руководстве по миграции API «Контакты» .

Методы без эквивалентов People API

Ниже перечислены методы getContacts в службе «Контакты», для которых отсутствуют эквивалентные способы поиска контактов в расширенной службе API People. С помощью расширенной службы API People можно выполнять поиск по полям 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)

Ниже перечислены методы getContacts из сервиса «Контакты», которые используют дополнительный параметр label . Вы можете использовать searchContacts из расширенного сервиса API «People» для получения контактов по аналогичному полю, но ограничить поиск конкретной меткой невозможно.

Методы с частичными эквивалентами
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Дополнительные функции, доступные с People API

При переходе на расширенный сервис People API вы получите доступ к следующим функциям People API, которые недоступны в сервисе Contacts:

  • Укажите источник данных . При поиске информации о человеке вы можете указать, где выполнять поиск, например, в контакте Google или в профиле Google.
  • Поиск людей по строке запроса . Вы можете получить список профилей и контактов, соответствующих определенной строке.
  • Пакетные запросы . Вы можете объединять в пакеты вызовы API People, чтобы сократить время выполнения скрипта.

Примеры кода для распространенных задач

В этом разделе перечислены распространённые задачи сервиса «Контакты». Примеры кода показывают, как создавать задачи с помощью расширенного сервиса People API.

Получить контактную группу по имени

В следующем примере кода показано, как получить группу контактов по ее имени, что эквивалентно getContactGroup(name) в службе контактов.

advanced/people.gs
/**
 * 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
/**
 * 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
/**
 * 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
/**
 * 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
/**
 * 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
/**
 * 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);
  }
}