Lettura e gestione dei contatti

Dopo aver completato i passaggi descritti in Prepararsi a utilizzare l'API People, puoi leggere e gestire i contatti.

I seguenti esempi di codice mostrano come inviare alcune richieste semplici. Per un elenco completo dei metodi, consulta la documentazione di riferimento.

Importante: è possibile modificare solo le persone basate sui contatti. Le persone basate su profilo lette utilizzando nome della risorsa "people/me" o da un ID account non possono essere modificate.

Elenca i contatti dell'utente

Per ottenere un elenco di persone nei contatti dell'utente, utilizza il seguente codice:

Protocollo

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;

Elenca i contatti dell'utente che sono stati modificati

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: le scritture potrebbero avere un ritardo di propagazione di diversi minuti per le richieste di sincronizzazione. Le sincronizzazioni incrementali non sono destinate ai casi d'uso di lettura dopo scrittura.

Per ulteriori dettagli sul comportamento di sincronizzazione, consulta ListConnections.

Cercare nei contatti dell'utente

Per cercare in tutti i contatti dell'utente, utilizza il seguente codice:

Protocollo

// 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 Ricerca utilizza una cache lazy che viene aggiornata dopo una richiesta. I client devono prima inviare una richiesta di ricerca di riscaldamento con una query vuota per assicurarsi che la cache contenga i dati più recenti.

Nota: la ricerca esegue una corrispondenza del prefisso della query con i campi di una persona. Ad esempio, una persona con il nome "nome di foo" corrisponde a query come "f", "fo", "foo", "foo n", "nam" e così via, ma non a "oo n".

Crea un nuovo contatto

Per creare un nuovo contatto, utilizza il seguente codice:

Protocollo

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

Utilizzo della quota per richiesta

• 1 richieste di lettura critiche (letture di contatti e profili)
• 1 richieste di scrittura critiche (creazione e aggiornamento dei contatti)
• 1 Scritture giornaliere dei contatti (totale)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.

Aggiornare un contatto esistente

Per aggiornare un contatto esistente, devi includere il campo person.metadata.sources.etag nella persona per il contatto da aggiornare per assicurarti che il contatto non sia cambiato dall'ultima lettura. Utilizza il seguente codice:

Protocollo

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

Utilizzo della quota per richiesta

• 1 richieste di lettura critiche (letture di contatti e profili)
• 1 richieste di scrittura critiche (creazione e aggiornamento dei contatti)
• 1 Scritture giornaliere dei contatti (totale)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.

Eliminare un contatto esistente

Per eliminare un contatto esistente, utilizza il seguente codice:

Protocollo

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

Java

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

Utilizzo della quota per richiesta

• 1 richiesta di scrittura (eliminazione di contatti e scrittura di gruppi di contatti)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.

Creare nuovi contatti in blocco

Per creare nuovi contatti in blocco, utilizza il seguente codice:

Protocollo

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

Utilizzo della quota per richiesta

• 6 richieste di lettura critiche (letture di contatti e profili)
• 6 richieste di scrittura critiche (creazione e aggiornamento dei contatti)
• 200 operazioni di scrittura dei contatti giornaliere (totale)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.

Aggiornare in blocco i contatti esistenti

Per aggiornare un contatto esistente, devi includere il campo person.metadata.sources.etag in ogni persona per il contatto da aggiornare per assicurarti che il contatto non sia cambiato dall'ultima lettura. Utilizza il seguente codice:

Protocollo

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

Utilizzo della quota per richiesta

• 6 richieste di lettura critiche (letture di contatti e profili)
• 6 richieste di scrittura critiche (creazione e aggiornamento dei contatti)
• 200 operazioni di scrittura dei contatti giornaliere (totale)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.

Eliminare in blocco i contatti esistenti

Per eliminare collettivamente i contatti esistenti, utilizza il seguente codice:

Protocollo

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

Utilizzo della quota per richiesta

• 10 richieste di scrittura (eliminazioni di contatti e scritture di gruppi di contatti)

Avviso: le richieste di mutazione per lo stesso utente devono essere inviate in sequenza per evitare un aumento della latenza e degli errori.