Passer du service Contacts au service avancé de l'API People

Apps Script a abandonné le service Contacts le 16 décembre 2022. Utilisez plutôt le service avancé de l'API People. L'API People s'appuie sur un protocole JSON plus récent pour fournir des fonctionnalités avancées, dont la possibilité de fusionner les contacts avec leurs profils.

Utilisez ce guide pour découvrir les méthodes du service Contacts qui n'ont pas d'équivalent dans le service avancé de l'API People, ce que vous pouvez utiliser à la place et trouver des exemples de code pour migrer les tâches courantes. Pour en savoir plus, consultez le guide de migration de l'API Contacts.

Méthodes sans équivalent dans l'API People

La liste suivante répertorie les méthodes getContacts du service Contacts qui n'ont pas de méthodes équivalentes pour rechercher des contacts dans le service avancé People API. Avec le service avancé de l'API People, vous pouvez effectuer des recherches par names, nickNames, emailAddresses, phoneNumbers et organizations d'un contact provenant de la source CONTACT.

Méthodes sans équivalents
  • 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 liste suivante répertorie les méthodes getContacts du service Contacts qui utilisent un paramètre label supplémentaire. Vous pouvez utiliser searchContacts à partir du service avancé de l'API People pour obtenir des contacts par le champ équivalent, mais vous ne pouvez pas limiter la recherche à un libellé spécifique.

Méthodes avec des équivalents partiels
  • getContactsByEmailAddress(query, label)
  • getContactsByName(query, label)
  • getContactsByPhone(query, label)

Fonctionnalités supplémentaires disponibles avec l'API People

Lorsque vous migrez vers le service avancé de l'API People, vous pouvez accéder aux fonctionnalités suivantes de l'API People, qui ne sont pas disponibles dans le service Contacts :

Exemples de code pour les tâches courantes

Cette section liste les tâches courantes du service Contacts. Les exemples de code montrent comment construire les tâches à l'aide du service avancé de l'API People.

Obtenir un groupe de contacts par son nom

L'exemple de code suivant montre comment obtenir un groupe de contacts par son nom, ce qui équivaut à getContactGroup(name) dans le service Contacts.

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

Obtenir un contact par adresse e-mail

L'exemple de code suivant montre comment obtenir un contact à partir de son adresse e-mail, ce qui équivaut à getContact(emailAddress) dans le service Contacts.

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

Obtenir tous les contacts

L'exemple de code suivant montre comment obtenir tous les contacts d'un utilisateur, ce qui équivaut à getContacts() dans le service Contacts.

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

Obtenir le nom complet d'un contact

L'exemple de code suivant montre comment obtenir le nom complet d'un contact, ce qui équivaut à getFullName() dans le service Contacts.

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

Obtenir tous les numéros de téléphone d'un contact

L'exemple de code suivant montre comment obtenir tous les numéros de téléphone d'un contact, ce qui équivaut à getPhones() dans le service 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);
  }
}

Obtenir un numéro de téléphone spécifique pour un contact

L'exemple de code suivant montre comment obtenir un numéro de téléphone spécifique pour un contact, ce qui équivaut à getPhoneNumber() dans le service Contacts.

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