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

Сервис «Контакты» в Google Apps Script был объявлен устаревшим 16 декабря 2022 года и полностью отключен 31 января 2025 года .

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

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

Методы, не имеющие эквивалентов в People API.

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

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

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

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

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

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

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

Приведенный ниже пример кода показывает, как получить группу контактов по ее имени, что эквивалентно функции getContactGroup в службе «Контакты».

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 в службе «Контакты».

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 в службе Contacts.

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