Kontakte lesen und verwalten

Nachdem Sie die Schritte unter Vorbereitungen für die Verwendung der People API ausgeführt haben, können Sie Kontakte lesen und verwalten.

Die folgenden Codebeispiele zeigen, wie Sie einige einfache Anfragen senden. Eine vollständige Liste der Methoden finden Sie in der Referenzdokumentation.

Wichtig :Nur personenbezogene Kontakte können geändert werden. Profilbasierte Personen, die über den Ressourcennamen "people/me" oder über eine Konto-ID gelesen werden, können nicht geändert werden.

Kontakte des Nutzers auflisten

Mit dem folgenden Code erhältst du eine Liste der Kontakte des Nutzers:

ProtokollJavaPythonPHP.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;

Liste der Kontakte des Nutzers, die sich geändert haben

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

Hinweis: Bei Schreibvorgängen kann es bei Synchronisierungsanfragen zu einer Verzögerung von mehreren Minuten kommen. Inkrementelle Synchronisierungen sind nicht für Anwendungsfälle des Typs „Lesen nach Schreiben“ vorgesehen.

Weitere Informationen zum Synchronisierungsverhalten finden Sie unter ListConnections.

In den Kontakten des Nutzers suchen

Wenn Sie in allen Kontakten des Nutzers suchen möchten, verwenden Sie den folgenden Code:

ProtokollJava

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

Wichtig :Die Suche verwendet einen Lazy-Cache, der nach einer Anfrage aktualisiert wird. Clients sollten zuerst eine Aufwärmsuchanfrage mit einer leeren Abfrage senden, um sicherzustellen, dass der Cache die neuesten Daten enthält.

Hinweis :Bei der Suche wird eine Präfixübereinstimmung der Abfrage mit den Feldern einer Person durchgeführt. Eine Person mit dem Namen „foo name“ wird beispielsweise mit Suchanfragen wie „f“, „fo“, „foo“, „foo n“, „nam“ usw. übereinstimmen, aber nicht mit „oo n“.

Neuen Kontakt erstellen

Verwenden Sie den folgenden Code, um einen neuen Kontakt zu erstellen:

ProtokollJava

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

Kontingentnutzung pro Anfrage

• 1 Kritische Leseanfragen (Lesen von Kontakten und Profilen)
• 1 kritische Schreibanfragen (Kontakte erstellen und aktualisieren)
• 1 Schreibvorgänge pro Tag (insgesamt)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.

Vorhandenen Kontakt aktualisieren

Wenn Sie einen vorhandenen Kontakt aktualisieren möchten, müssen Sie das Feld person.metadata.sources.etag in der Person für den zu aktualisierenden Kontakt angeben, um sicherzustellen, dass sich der Kontakt seit Ihrer letzten Lesevorgang nicht geändert hat. Verwenden Sie den folgenden Code:

ProtokollJava

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

Kontingentnutzung pro Anfrage

• 1 Kritische Leseanfragen (Lesen von Kontakten und Profilen)
• 1 kritische Schreibanfragen (Kontakte erstellen und aktualisieren)
• 1 Schreibvorgänge pro Tag (insgesamt)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.

Vorhandenen Kontakt löschen

Verwenden Sie den folgenden Code, um einen vorhandenen Kontakt zu löschen:

ProtokollJava

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

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

Kontingentnutzung pro Anfrage

• 1 Schreibanfragen (Löschen von Kontakten und Schreiben an Kontaktgruppen)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.

Neue Kontakte im Bulk-Verfahren erstellen

Wenn Sie mehrere neue Kontakte gleichzeitig erstellen möchten, verwenden Sie den folgenden Code:

ProtokollJava

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

Kontingentnutzung pro Anfrage

• 6 kritische Leseanfragen (Kontakte und Profile lesen)
• 6 kritische Schreibanfragen (Kontakte erstellen und aktualisieren)
• 200 Schreibvorgänge pro Tag (insgesamt)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.

Vorhandene Kontakte im Batch aktualisieren

Wenn Sie einen vorhandenen Kontakt aktualisieren möchten, müssen Sie für jede Person, für die der Kontakt aktualisiert werden soll, das Feld person.metadata.sources.etag angeben, um sicherzustellen, dass sich der Kontakt seit Ihrer letzten Lesevorgang nicht geändert hat. Verwenden Sie den folgenden Code:

ProtokollJava

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

Kontingentnutzung pro Anfrage

• 6 kritische Leseanfragen (Kontakte und Profile lesen)
• 6 kritische Schreibanfragen (Kontakte erstellen und aktualisieren)
• 200 Schreibvorgänge pro Tag (insgesamt)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.

Vorhandene Kontakte im Bulk-Verfahren löschen

Verwenden Sie den folgenden Code, um vorhandene Kontakte im Bulk-Verfahren zu löschen:

ProtokollJava

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

Kontingentnutzung pro Anfrage

• 10 Schreibanfragen (Löschen von Kontakten und Schreiben an Kontaktgruppen)

Warnung :Anfragen zum Ändern von Daten für denselben Nutzer sollten nacheinander gesendet werden, um eine erhöhte Latenz und Fehler zu vermeiden.