Lire et gérer les contacts

Une fois que vous avez suivi la procédure décrite dans la section Préparer l'utilisation de l'API People, vous pouvez lire et gérer les contacts.

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

Important :Seuls les contacts peuvent être modifiés. Les personnes basées sur le profil lues à l'aide du nom de ressource "people/me" ou d'un ID de compte ne peuvent pas être modifiées.

Lister les contacts de l'utilisateur

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

ProtocoleJavaPythonPHP.NET

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

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

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

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

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 changé

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 présenter 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 synchronisation, consultez ListConnections.

Rechercher dans les contacts de l'utilisateur

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

ProtocoleJava

// 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

// 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 paresseux qui est mis à jour après une requête. Les clients doivent d'abord envoyer une requête de préchauffage de recherche avec une requête vide pour s'assurer que le cache contient les dernières données.

Remarque :La recherche effectue une correspondance de préfixe de la requête avec les champs d'une personne. Par exemple, une personne dont le nom est "nom foo" correspond à des 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:

ProtocoleJava

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

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 requête de lecture critique (lectures de contacts et de profils)
• 1 requêtes d'écriture critiques (création et mise à jour de contacts)
• 1 Écritures quotidiennes de contacts (total)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.

Modifier un contact existant

Pour mettre à jour un contact existant, vous devez inclure le champ person.metadata.sources.etag dans la personne à mettre à jour pour vous assurer qu'elle n'a pas changé depuis votre dernière lecture. Utilisez le code suivant:

ProtocoleJava

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

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 requête de lecture critique (lectures de contacts et de profils)
• 1 requêtes d'écriture critiques (création et mise à jour de contacts)
• 1 Écritures quotidiennes de contacts (total)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.

Supprimer un contact existant

Pour supprimer un contact existant, utilisez le code suivant:

ProtocoleJava

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

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

Utilisation du quota par requête

• 1 Requêtes d'écriture (suppressions de contacts et écritures dans des groupes de contacts)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.

Créer des contacts par lot

Pour créer des contacts par lot, utilisez le code suivant:

ProtocoleJava

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

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

• 6 requêtes de lecture critiques (lectures de contacts et de profils)
• 6 requêtes d'écriture critiques (création et mise à jour de contacts)
• 200 écritures quotidiennes dans les contacts (total)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.

Mettre à jour des 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 à mettre à jour pour vous assurer qu'elle n'a pas changé depuis votre dernière lecture. Utilisez le code suivant:

ProtocoleJava

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

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

• 6 requêtes de lecture critiques (lectures de contacts et de profils)
• 6 requêtes d'écriture critiques (création et mise à jour de contacts)
• 200 écritures quotidiennes dans les contacts (total)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.

Supprimer des contacts existants de manière groupée

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

ProtocoleJava

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

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 dans des groupes de contacts)

Avertissement :Les requêtes de modification pour le même utilisateur doivent être envoyées de manière séquentielle pour éviter d'augmenter la latence et les échecs.