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

Важно ! Перенесите свои сценарии из службы контактов в расширенную службу People API до того, как Apps Script отключит службу контактов в марте 2023 г.

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

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

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

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

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

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

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

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

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

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

В этом разделе перечислены общие задачи службы контактов. В примерах кода показано, как создавать задачи с помощью расширенной службы People API.

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

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

продвинутый/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) в службе контактов.

продвинутый/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() в службе контактов.

продвинутый/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() в службе контактов.

продвинутый/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() в службе контактов.

продвинутый/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() в службе контактов.

продвинутый/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);
  }
}