Migrar do serviço Contatos para o serviço avançado da API People

O Google Apps Script descontinuou o serviço de contatos em 16 de dezembro de 2022 e vai desativar o serviço em 31 de janeiro de 2025.

Em vez disso, use o serviço avançado da API People. A API People usa um protocolo JSON mais recente e oferece recursos avançados, como a fusão de contatos com perfis.

Use este guia para saber quais métodos do serviço de contatos não têm equivalentes no serviço avançado da API People, o que você pode usar em vez disso e encontrar exemplos de código para migrar tarefas comuns. Para mais informações, consulte o Guia de migração da API Contacts.

Métodos sem equivalentes na API People

A lista a seguir mostra os métodos getContacts no serviço de contatos que não têm maneiras equivalentes de pesquisar contatos no serviço avançado da API People. Com o serviço avançado da API People, é possível pesquisar pelos campos names, nickNames, emailAddresses, phoneNumbers e organizations de um contato que são da fonte CONTACT.

Métodos sem equivalentes

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)

A tabela a seguir lista os métodos getContacts do serviço de contatos que usam um parâmetro label extra. Embora o serviço avançado da API People permita receber contatos pelo campo equivalente usando searchContacts, não é possível limitar a pesquisa a um rótulo específico.

Métodos com equivalentes parciais
getContactsByEmailAddress(query, label) getContactsByName(query, label) getContactsByPhone(query, label)

Outros recursos disponíveis com a API People

Ao migrar para o serviço avançado da API People, você pode acessar os seguintes recursos da API People que não estão disponíveis no serviço de contatos:

• Especifique a fonte de dados: ao pesquisar informações sobre uma pessoa, você pode especificar onde pesquisar, como um contato ou perfil do Google.
• Pesquisar pessoas por uma string de consulta: você pode receber uma lista de perfis e contatos que correspondem a uma string específica.
• Solicitações em lote: é possível agrupar as chamadas da API People para reduzir o tempo de execução do script.

Exemplos de código para tarefas comuns

Esta seção lista tarefas comuns do serviço de contatos. Os exemplos de código mostram como construir as tarefas usando o serviço avançado da API People.

Obter um grupo de contatos por nome

O exemplo de código a seguir mostra como receber um grupo de contatos pelo nome, que é o equivalente a getContactGroup no serviço de contatos.

advanced/people.gs

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

Receber um contato por endereço de e-mail

O exemplo de código a seguir mostra como receber um contato pelo endereço de e-mail dele, que é o equivalente a getContact no serviço de contatos.

advanced/people.gs

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

Receber todos os contatos

O exemplo de código a seguir mostra como receber todos os contatos de um usuário, o que é equivalente a getContacts no serviço de contatos.

advanced/people.gs

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

Receber o nome completo de um contato

O exemplo de código a seguir mostra como receber o nome completo de um contato, que é o equivalente a getFullName no serviço de contatos.

advanced/people.gs

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

Receber todos os números de telefone de um contato

O exemplo de código a seguir mostra como receber todos os números de telefone de um contato, o que equivale a getPhones no serviço de contatos.

advanced/people.gs

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

Encontrar um número de telefone específico de um contato

O exemplo de código a seguir mostra como receber um número de telefone específico de um contato, o que equivale a getPhoneNumber no serviço de contatos.

advanced/people.gs

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