Kontakte lesen und verwalten

Wenn Sie die Schritte unter Vorbereitung auf 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 Personen, die mit Kontakten verknüpft sind, können geändert werden. Profilbasierte Personen, die den Ressourcennamen "people/me" oder eine Konto-ID verwenden, können nicht geändert werden.

Kontakte des Nutzers auflisten

Verwenden Sie den folgenden Code, um eine Liste der Personen in den Kontakten des Nutzers abzurufen:

Protokoll

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;

Geänderte Kontakte des Nutzers auflisten

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: Schreibvorgänge können bei Synchronisierungsanfragen mit einer Verzögerung von mehreren Minuten übernommen werden. Inkrementelle Synchronisierungen sind nicht für den Lese-nach-Schreib-Anwendungsfall vorgesehen.

Weitere Informationen zum Synchronisierungsverhalten finden Sie unter ListConnections.

In den Kontakten des Nutzers suchen

Verwenden Sie den folgenden Code, um in allen Kontakten des Nutzers zu suchen:

Protokoll

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

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: Die Suche gleicht ein Präfix der Abfrage mit den Feldern einer Person ab. Eine Person mit dem Namen „foo name“ stimmt beispielsweise mit Abfragen wie „f“, „fo“, „foo“, „foo n“, „nam“ usw. überein, aber nicht mit „oo n“.

Neuen Kontakt erstellen

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

Protokoll

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

Kontingentnutzung pro Anfrage

• 1 Kritische Leseanfragen (Kontakt- und Profillesevorgänge)
• 1 Kritische Schreibanfragen (Kontakterstellung und -aktualisierung)
• 1 tägliche Kontakt-Schreibvorgänge (insgesamt)

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

Bestehenden Kontakt aktualisieren

Wenn Sie einen vorhandenen Kontakt aktualisieren möchten, müssen Sie in die Person für die Aktualisierung des Kontakts das Feld person.metadata.sources.etag einfügen. So ist sichergestellt, dass der Kontakt seit dem letzten Lesen nicht geändert wurde. Verwenden Sie den folgenden Code:

Protokoll

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

Kontingentnutzung pro Anfrage

• 1 Kritische Leseanfragen (Kontakt- und Profillesevorgänge)
• 1 Kritische Schreibanfragen (Kontakterstellung und -aktualisierung)
• 1 tägliche Kontakt-Schreibvorgänge (insgesamt)

Warnung :Änderungsanfragen 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:

Protokoll

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

Java

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

Kontingentnutzung pro Anfrage

• 1 Schreibanfragen (Kontaktlöschungen und Schreibvorgänge für Kontaktgruppen)

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

Neue Kontakte im Batch erstellen

Verwenden Sie den folgenden Code, um neue Kontakte im Batch zu erstellen:

Protokoll

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

Kontingentnutzung pro Anfrage

• 6 Kritische Leseanfragen (Kontakt- und Profillesevorgänge)
• 6 Kritische Schreibanfragen (Kontakterstellung und -aktualisierung)
• 200 Schreibvorgänge pro Tag (insgesamt)

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

Bestehende Kontakte im Batch aktualisieren

Wenn Sie einen vorhandenen Kontakt aktualisieren möchten, müssen Sie für jede Person das Feld person.metadata.sources.etag angeben, damit der Kontakt aktualisiert wird. So ist sichergestellt, dass der Kontakt seit dem letzten Lesen nicht geändert wurde. Verwenden Sie den folgenden Code:

Protokoll

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

Kontingentnutzung pro Anfrage

• 6 Kritische Leseanfragen (Kontakt- und Profillesevorgänge)
• 6 Kritische Schreibanfragen (Kontakterstellung und -aktualisierung)
• 200 Schreibvorgänge pro Tag (insgesamt)

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

Bestehende Kontakte im Batch löschen

Verwenden Sie den folgenden Code, um vorhandene Kontakte im Batch zu löschen:

Protokoll

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

Kontingentnutzung pro Anfrage

• 10 Schreibanfragen (Kontaktlöschungen und Schreibvorgänge für Kontaktgruppen)

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