Membaca dan Mengelola Kontak

Setelah menyelesaikan langkah-langkah di Bersiap Menggunakan People API, Anda siap membaca dan mengelola kontak.

Contoh kode berikut menunjukkan cara mengirim beberapa permintaan sederhana. Untuk mengetahui daftar lengkap metode, lihat dokumentasi referensi.

Penting: Hanya orang berbasis kontak yang dapat diubah. Orang berbasis profil yang dibaca menggunakan nama resource "people/me" atau oleh ID akun tidak dapat diubah.

Mencantumkan kontak pengguna

Untuk mendapatkan daftar orang di kontak pengguna, gunakan kode berikut:

Protokol

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;

Mencantumkan kontak pengguna yang telah berubah

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

Catatan: Operasi tulis mungkin memiliki penundaan penerapan selama beberapa menit untuk permintaan sinkronisasi. Sinkronisasi inkremental tidak ditujukan untuk kasus penggunaan baca-setelah-tulis.

Detail selengkapnya tentang perilaku sinkronisasi di ListConnections.

Menelusuri kontak pengguna

Untuk menelusuri semua kontak pengguna, gunakan kode berikut:

Protokol

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

Penting: Penelusuran menggunakan cache lambat yang diperbarui setelah permintaan. Klien harus terlebih dahulu mengirim permintaan penelusuran pemanasan dengan kueri kosong untuk memastikan cache memiliki data terbaru.

Catatan: Penelusuran melakukan pencocokan awalan kueri dengan kolom pada orang. Misalnya, seseorang dengan nama "nama foo" cocok dengan kueri seperti "f", "fo", "foo", "foo n", "nam", dll., tetapi tidak cocok dengan "oo n".

Buat kontak baru

Untuk membuat kontak baru, gunakan kode berikut:

Protokol

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

Penggunaan kuota per permintaan

• 1 Permintaan operasi baca penting (Pembacaan Kontak dan Profil)
• 1 Permintaan tulis penting (Pembuatan dan Pembaruan Kontak)
• 1 Daily Contact Writes (Total)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.

Memperbarui kontak yang ada

Untuk memperbarui kontak yang ada, Anda harus menyertakan kolom person.metadata.sources.etag di orang agar kontak diperbarui untuk memastikan kontak tidak berubah sejak Anda terakhir membacanya. Gunakan kode berikut:

Protokol

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

Penggunaan kuota per permintaan

• 1 Permintaan operasi baca penting (Pembacaan Kontak dan Profil)
• 1 Permintaan tulis penting (Pembuatan dan Pembaruan Kontak)
• 1 Daily Contact Writes (Total)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.

Menghapus kontak yang ada

Untuk menghapus kontak yang ada, gunakan kode berikut:

Protokol

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

Java

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

Penggunaan kuota per permintaan

• 1 Permintaan tulis (Penghapusan Kontak dan Tulis Grup Kontak)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.

Membuat kontak baru secara massal

Untuk membuat kontak baru secara massal, gunakan kode berikut:

Protokol

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

Penggunaan kuota per permintaan

• 6 Permintaan baca penting (Baca Kontak dan Profil)
• 6 Permintaan tulis penting (Pembuatan dan Pembaruan Kontak)
• 200 Operasi Tulis Kontak Harian (Total)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.

Memperbarui kontak yang ada secara massal

Untuk memperbarui kontak yang ada, Anda harus menyertakan kolom person.metadata.sources.etag di setiap orang agar kontak diperbarui untuk memastikan kontak tidak berubah sejak Anda terakhir membacanya. Gunakan kode berikut:

Protokol

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

Penggunaan kuota per permintaan

• 6 Permintaan baca penting (Baca Kontak dan Profil)
• 6 Permintaan tulis penting (Pembuatan dan Pembaruan Kontak)
• 200 Operasi Tulis Kontak Harian (Total)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.

Menghapus kontak yang ada secara massal

Untuk menghapus kontak yang ada secara massal, gunakan kode berikut:

Protokol

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

Penggunaan kuota per permintaan

• 10 Permintaan tulis (Penghapusan Kontak dan Tulis Grup Kontak)

Peringatan: Permintaan mutasi untuk pengguna yang sama harus dikirim secara berurutan untuk menghindari peningkatan latensi dan kegagalan.