Lire et gérer les contacts

Une fois que vous avez terminé les étapes de la section Préparez-vous à utiliser l'API People, vous pouvez lire et gérer les contacts.

Les exemples de code suivants montrent comment envoyer quelques requêtes simples. Pour obtenir la liste complète des méthodes, consultez la documentation de référence.

Important :Seules les personnes basées sur des contacts peuvent être modifiées. Vous ne pouvez pas modifier les utilisateurs qui lisent des utilisateurs basés sur un profil à l'aide du nom de ressource "people/me" ou d'un ID de compte.

Lister les contacts de l'utilisateur

Pour obtenir la liste des personnes figurant dans les contacts de l'utilisateur, utilisez le code suivant:

Protocole

GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

ListConnectionsResponse response = peopleService.people().connections().list("people/me")
    .setPersonFields("names,emailAddresses")
    .execute();
List<Person> people = response.getConnections();

Python

people = people_service.people().connections()
    .list('people/me', personFields='names,emailAddresses')

PHP

$people = $people_service->people_connections->listPeopleConnections(
    'people/me', array('personFields' => 'names,emailAddresses'));

.NET

PeopleResource.ConnectionsResource.ListRequest peopleRequest =
    peopleService.People.Connections.List("people/me");
peopleRequest.PersonFields = "names,emailAddresses";
ListConnectionsResponse response = peopleRequest.Execute();
IList<Person> people = response.Connections;

Lister les contacts de l'utilisateur qui ont été modifiés

Java

// Initial request
ListConnectionsResponse fullSyncResponse = peopleService.people().connections().list("people/me")
    .setPersonFields("metadata,names,emailAddresses")
    .setRequestSyncToken(true)
    .execute();
// Fetch all the pages
while (fullSyncResponse.getNextPageToken() != null) {
  fullSyncResponse = peopleService.people().connections().list("people/me")
      .setPersonFields("metadata,names,emailAddresses")
      .setRequestSyncToken(true)
      .setPageToken(fullSyncResponse.getNextPageToken())
      .execute();
}

// Some time passes

// Fetch incremental changes using the sync token returned in the last fullSyncResponse.
try {
  ListConnectionsResponse incrementalSyncResponse = peopleService.people().connections().list("people/me")
      .setPersonFields("metadata,names,emailAddresses")
      .setSyncToken(fullSyncResponse.getNextSyncToken())
      .execute();
  for (Person person : incrementalSyncResponse.getConnections()) {
    handlePerson(person);
  }

  // Fetch all the pages
  while (incrementalSyncResponse.getNextPageToken() != null) {
    incrementalSyncResponse = peopleService.people().connections().list("people/me")
        .setPersonFields("metadata,names,emailAddresses")
        .setSyncToken(fullSyncResponse.getNextSyncToken())
        .setPageToken(incrementalSyncResponse.getNextPageToken())
        .execute();
    for (Person person : incrementalSyncResponse.getConnections()) {
      handlePerson(person);
    }
  }
} catch (GoogleJsonResponseException e) {
  if (e.getStatusCode() == 410) {
    // Sync token expired. Make full sync request.
  }
}

void handlePerson(Person person) {
  if (person.getMetadata().getDeleted()) {
    // Handle deleted person
  } else {
    // Handle changed person
  }
}

Remarque :Les écritures peuvent avoir un délai de propagation de plusieurs minutes pour les requêtes de synchronisation. Les synchronisations incrémentielles ne sont pas destinées aux cas d'utilisation de lecture après écriture.

Pour en savoir plus sur le comportement de la synchronisation, consultez ListConnections.

Rechercher dans les contacts de l'utilisateur

Pour rechercher tous les contacts de l'utilisateur, utilisez le code suivant:

Protocole

// Warmup cache
GET /v1/people:searchContacts?query=&readMask=names,emailAddresses HTTP/1.1
Host: people.googleapis.com


// Send search request after several seconds
GET /v1/people:searchContacts?query=query&readMask=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

// Warmup cache
SearchResponse response = peopleService.people().searchContacts()
    .setQuery("")
    .setReadMask("names,emailAddresses")
    .execute();


// Wait a few seconds
Thread.sleep(5);

// Send search request
SearchResponse response = peopleService.people().searchContacts()
    .setQuery("query")
    .setReadMask("names,emailAddresses")
    .execute();

Important :La recherche utilise un cache différé mis à jour après une requête. Les clients doivent d'abord envoyer une requête de recherche de préchauffage avec une requête vide pour s'assurer que le cache dispose des données les plus récentes.

Remarque :La recherche établit une correspondance entre le préfixe de la requête et les champs d'une personne. Par exemple, une personne portant le nom "foo name" correspond aux requêtes telles que "f", "fo", "foo", "foo n", "nam", etc., mais pas "oo n".

Créer un contact

Pour créer un contact, utilisez le code suivant:

Protocole

POST /v1/people:createContact HTTP/1.1
Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] }
Host: people.googleapis.com

Java

Person contactToCreate = new Person();
List<Name> names = new ArrayList<>();
names.add(new Name().setGivenName("John").setFamilyName("Doe"));
contactToCreate.setNames(names);

Person createdContact = peopleService.people().createContact(contactToCreate).execute();

Utilisation du quota par requête

• 1 Demandes de lecture critiques (lectures de contacts et de profils)
• 1 Demandes d'écriture critiques (création et mise à jour du contact)
• 1 écriture de contact quotidienne (total)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.

Mettre à jour un contact existant

Pour mettre à jour un contact existant, vous devez inclure le champ person.metadata.sources.etag dans la personne afin que le contact soit mis à jour et que le contact n'ait pas changé depuis votre dernière lecture. Utilisez le code suivant:

Protocole

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1
Body: {
    "resourceName": "resource_name",
    "etag": "etag",
    "emailAddresses": [{ "value": "[e-mail]" }],
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

List<EmailAddress> emailAddresses = new ArrayList<>();
emailAddresses.add(new EmailAddress().setValue("[e-mail]"));
contactToUpdate.setEmailAddresses(emailAddresses);

Person updatedContact = peopleService.people()
    .updateContact(contactToUpdate.getResourceName(), contactToUpdate)
    .setUpdatePersonFields("emailAddresses")
    .execute();

Utilisation du quota par requête

• 1 Demandes de lecture critiques (lectures de contacts et de profils)
• 1 Demandes d'écriture critiques (création et mise à jour du contact)
• 1 écriture de contact quotidienne (total)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.

Supprimer un contact existant

Pour supprimer un contact existant, utilisez le code suivant:

Protocole

DELETE /v1/resource_name:deleteContact HTTP/1.1
Host: people.googleapis.com

Java

peopleService.people().deleteContact("resource_name").execute();

Utilisation du quota par requête

• 1 Demandes d'écriture (suppressions de contacts et écritures de groupes de contacts)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.

Créer des contacts simultanément

Pour créer des contacts de manière groupée, utilisez le code suivant:

Protocole

POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1
Body: {
  "contacts": [
    {
      "contactPerson": {
        "names": [
          {
            "givenName": "John",
            "familyName": "Doe"
          }
        ]
      }
    }
  ]
}
Host: people.googleapis.com

Java

Person person1 = new Person();
person1.setNames(ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));
ContactToCreate contactToCreate1 = new ContactToCreate();
contactToCreate1.setContactPerson(person1);

Person person2 = new Person();
person2.setNames(ImmutableList.of(new Name().setGivenName("Bob").setFamilyName("Dylan")));
ContactToCreate contactToCreate2 = new ContactToCreate();
contactToCreate2.setContactPerson(person2);

BatchCreateContactsRequest request = new BatchCreateContactsRequest();
request.setContacts(ImmutableList.of(contactToCreate1, contactToCreate2)).setReadMask("names");

BatchCreateContactsResponse response =
    peopleService.people().batchCreateContacts(request).execute();

Utilisation du quota par requête

• Six requêtes de lecture critiques (lectures de contacts et de profils)
• Six demandes d'écriture critiques (création et mise à jour du contact)
• 200 écritures de contact quotidiennes (total)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.

Mettre à jour les contacts existants de manière groupée

Pour mettre à jour un contact existant, vous devez inclure le champ person.metadata.sources.etag dans chaque personne afin que le contact soit mis à jour et que le contact n'ait pas changé depuis votre dernière lecture. Utilisez le code suivant:

Protocole

POST /v1/people:batchUpdateContacts?updateMask=names&readMask=names,emailAddresses HTTP/1.1
Body: {
  "contacts": {
    "resource_name": {
      "emailAddresses": [
        {
          "value": "[e-mail]"
        }
      ]
      "etag": "etag"
    }
  }
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

contactToUpdate.setNames(
    ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));

BatchUpdateContactsRequest request = new BatchUpdateContactsRequest();
ImmutableMap<String, Person> map =
    ImmutableMap.of(contactToUpdate.getResourceName(), contactToUpdate);
request.setContacts(map).setUpdateMask("names").setReadMask("names,emailAddresses");

BatchUpdateContactsResponse response =
    peopleService.people().batchUpdateContacts(request).execute();

Utilisation du quota par requête

• Six requêtes de lecture critiques (lectures de contacts et de profils)
• Six demandes d'écriture critiques (création et mise à jour du contact)
• 200 écritures de contact quotidiennes (total)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.

Supprimer de façon groupée des contacts existants

Pour supprimer des contacts existants de manière groupée, utilisez le code suivant:

Protocole

POST /v1/people:batchDeleteContacts HTTP/1.1
Body: {"resource_names": ["resource_name"]}
Host: people.googleapis.com

Java

BatchDeleteContactsRequest request = new BatchDeleteContactsRequest();

request.setResourceNames(ImmutableList.of(resource_name));

peopleService.people().batchDeleteContacts(request).execute();

Utilisation du quota par requête

• 10 requêtes d'écriture (suppressions de contacts et écritures de groupes de contacts)

Avertissement :Les requêtes de mutation pour un même utilisateur doivent être envoyées de manière séquentielle afin d'éviter une latence accrue et des échecs.