Leer y administrar contactos

Una vez que completes los pasos en Prepárate para usar la API de People, estarás listo para leer y administrar contactos.

En las siguientes muestras de código, se indica cómo enviar algunas solicitudes simples. Para ver una lista completa de métodos, consulta la documentación de referencia.

Importante: Solo se pueden modificar las personas basadas en contactos. No se pueden modificar las personas basadas en perfiles que leen con el nombre del recurso "people/me" o con un ID de cuenta.

Obtén una lista de los contactos del usuario

Para obtener una lista de las personas en los contactos del usuario, usa el siguiente código:

Protocolo

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;

Enumera los contactos del usuario que cambiaron

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

Nota: Las operaciones de escritura pueden tener un retraso de propagación de varios minutos en las solicitudes de sincronización. Las sincronizaciones incrementales no están diseñadas para casos de uso de lectura después de escritura.

Obtén más detalles sobre el comportamiento de la sincronización en ListConnections.

Buscar en los contactos del usuario

Para buscar en todos los contactos del usuario, usa el siguiente código:

Protocolo

// 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();

Importante: La Búsqueda usa una caché diferida que se actualiza después de una solicitud. Los clientes primero deben enviar una solicitud de búsqueda de preparación con una consulta vacía para asegurarse de que la caché tenga los datos más recientes.

Nota: La búsqueda hace una coincidencia de prefijo de la consulta con los campos de una persona. Por ejemplo, una persona con el nombre “foo name” coincide con consultas como “f”, “fo”, “foo”, “foo n”, “nam”, etc., pero no con “oo n”.

Crear un contacto nuevo

Para crear un contacto nuevo, usa el siguiente código:

Protocolo

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

Uso de cuota por solicitud

• 1 solicitudes de lectura crítica (lecturas de contactos y perfiles)
• 1 solicitud de escritura crítica (creación de contactos y actualizaciones)
• 1 escritura diaria de contacto (total)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.

Actualizar un contacto existente

Si quieres actualizar un contacto existente, debes incluir el campo person.metadata.sources.etag en la persona para que el contacto se actualice y asegúrate de que no haya cambiado desde tu última lectura. Usa el siguiente código:

Protocolo

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

Uso de cuota por solicitud

• 1 solicitudes de lectura crítica (lecturas de contactos y perfiles)
• 1 solicitud de escritura crítica (creación de contactos y actualizaciones)
• 1 escritura diaria de contacto (total)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.

Cómo borrar un contacto existente

Para borrar un contacto existente, usa el siguiente código:

Protocolo

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

Java

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

Uso de cuota por solicitud

• 1 solicitud de escritura (eliminaciones de contactos y escrituras de grupos de contactos)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.

Crear contactos nuevos por lotes

Para crear contactos nuevos por lotes, usa el siguiente código:

Protocolo

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

Uso de cuota por solicitud

• 6 solicitudes de operaciones de lectura críticas (lecturas de contactos y perfiles)
• 6 solicitudes de escritura crítica (creación de contactos y actualizaciones)
• 200 operaciones de escritura de contactos diarias (total)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.

Actualizar por lotes los contactos existentes

Para actualizar un contacto existente, debes incluir el campo person.metadata.sources.etag en cada persona a fin de que el contacto se actualice para asegurarte de que no haya cambiado desde tu última lectura. Usa el siguiente código:

Protocolo

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

Uso de cuota por solicitud

• 6 solicitudes de operaciones de lectura críticas (lecturas de contactos y perfiles)
• 6 solicitudes de escritura crítica (creación de contactos y actualizaciones)
• 200 operaciones de escritura de contactos diarias (total)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.

Borrar contactos existentes por lotes

Para borrar por lotes los contactos existentes, usa el siguiente código:

Protocolo

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

Uso de cuota por solicitud

• 10 solicitudes de escritura (eliminaciones de contactos y escrituras de grupos de contactos)

Advertencia: Las solicitudes de mutación para el mismo usuario se deben enviar de forma secuencial para evitar aumentos de latencia y fallas.