Eseguire la migrazione dal servizio Contatti al servizio avanzato dell'API People

Google Apps Script ha ritirato il servizio Contatti il 16 dicembre 2022 e lo ha disattivato il 31 gennaio 2025.

Utilizza invece il servizio avanzato dell'API People. L'API People utilizza un protocollo JSON più recente e fornisce funzionalità avanzate, come l'unione dei contatti con i profili.

Utilizza questa guida per scoprire quali metodi del servizio Contatti non hanno un equivalente nel servizio avanzato dell'API People, cosa puoi utilizzare in alternativa e trovare esempi di codice per la migrazione delle attività comuni. Per ulteriori informazioni, consulta la guida alla migrazione dell'API Contacts.

Metodi senza equivalenti nell'API People

I seguenti elenchi mostrano i metodi getContacts nel servizio Contatti che non hanno modi equivalenti per cercare i contatti nel servizio avanzato dell'API People. Con il servizio avanzato dell'API People, puoi eseguire ricerche in base ai campi names, nickNames, emailAddresses, phoneNumbers e organizations di un contatto provenienti dall'origine CONTACT.

Metodi senza equivalenti
  • 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)

La tabella seguente elenca i metodi getContacts del servizio Contatti che utilizzano un parametro label aggiuntivo. Sebbene il servizio avanzato dell'API People ti consenta di ottenere i contatti in base al campo equivalente utilizzando searchContacts, non puoi limitare la ricerca a un'etichetta specifica.

Metodi con equivalenti parziali
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Funzionalità aggiuntive disponibili con l'API People

Quando esegui la migrazione al servizio avanzato dell'API People, puoi accedere alle seguenti funzionalità dell'API People non disponibili nel servizio Contatti:

Esempi di codice per attività comuni

Questa sezione elenca le attività comuni del servizio Contatti. Gli esempi di codice mostrano come costruire le attività utilizzando il servizio avanzato dell'API People.

Ottenere un gruppo di contatti per nome

Il seguente esempio di codice mostra come ottenere un gruppo di contatti in base al nome, che equivale a getContactGroup nel servizio Contatti.

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

Ottenere un contatto tramite indirizzo email

L'esempio di codice seguente mostra come ottenere un contatto dal suo indirizzo email, che equivale a getContact nel servizio Contatti.

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

Recuperare tutti i contatti

Il seguente esempio di codice mostra come ottenere tutti i contatti di un utente, che equivale a getContacts nel servizio Contatti.

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

Ottenere il nome completo di un contatto

Il seguente esempio di codice mostra come ottenere il nome completo di un contatto, che è l'equivalente di getFullName nel servizio Contatti.

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

Visualizzare tutti i numeri di telefono di un contatto

L'esempio di codice seguente mostra come ottenere tutti i numeri di telefono di un contatto, che equivale a getPhones nel servizio Contatti.

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

Ottenere un numero di telefono specifico per un contatto

Il seguente esempio di codice mostra come ottenere un numero di telefono specifico per un contatto, che equivale a getPhoneNumber nel servizio Contatti.

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