Leer y administrar contactos

Después de completar los pasos de Prepárate para usar la API de People, ya puedes leer y administrar contactos.

En las siguientes muestras de código, se muestra cómo enviar algunas solicitudes simples. Para obtener 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 se leen con el nombre del recurso "people/me" o con un ID de cuenta.

Muestra la lista de 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;

Muestra una lista de 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 una demora de propagación de varios minutos para las solicitudes de sincronización. Las sincronizaciones incrementales no están diseñadas para casos de uso de lectura después de la escritura.

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

Buscar en los contactos del usuario

Para buscar 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 realiza una concordancia de prefijo de la consulta con los campos de una persona. Por ejemplo, una persona con el nombre "foo name" coincide con búsquedas como "f", "fo", "foo", "foo n", "nam", etcétera, 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 solicitud de lectura crítica (lecturas de contactos y perfiles)
• 1 solicitud de escritura crítica (creación y actualización de contactos)
• 1 operación de escritura diaria de contactos (total)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor latencia y fallas.

Cómo actualizar un contacto existente

Para actualizar un contacto existente, debes incluir el campo person.metadata.sources.etag en la persona para que se actualice el contacto y asegurarte de que no haya cambiado desde la última vez que lo leíste. 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 solicitud de lectura crítica (lecturas de contactos y perfiles)
• 1 solicitud de escritura crítica (creación y actualización de contactos)
• 1 operación de escritura diaria de contactos (total)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor 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 (borrar contactos y escribir en grupos de contactos)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor latencia y fallas.

Cómo 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 lectura críticas (lecturas de contactos y perfiles)
• 6 solicitudes de escritura críticas (creación y actualización de contactos)
• 200 operaciones de escritura de contactos diarias (total)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor latencia y fallas.

Actualiza contactos existentes por lotes

Para actualizar un contacto existente, debes incluir el campo person.metadata.sources.etag en cada persona para que el contacto se actualice y te asegures de que no haya cambiado desde la ú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 lectura críticas (lecturas de contactos y perfiles)
• 6 solicitudes de escritura críticas (creación y actualización de contactos)
• 200 operaciones de escritura de contactos diarias (total)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor latencia y fallas.

Borra contactos existentes de forma masiva

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 (borradores de contactos y escrituras en grupos de contactos)

Advertencia: Las solicitudes de mutación para el mismo usuario deben enviarse de forma secuencial para evitar una mayor latencia y fallas.