Membaca dan Mengelola Kontak

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

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

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

Membuat daftar kontak pengguna

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

Protocol

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;

Menampilkan daftar 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 mengalami penundaan propagasi selama beberapa menit untuk permintaan sinkronisasi. Sinkronisasi inkremental tidak dimaksudkan untuk kasus penggunaan baca setelah tulis.

Detail selengkapnya tentang perilaku sinkronisasi di ListConnections.

Menelusuri kontak pengguna

Untuk menelusuri semua kontak pengguna, gunakan kode berikut:

Protocol

// 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 ada 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 pengguna. Misalnya, orang dengan nama "foo name" 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:

Protocol

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 operasi tulis penting (Pembuatan dan Update Kontak)
• 1 Penulisan Kontak Harian (Total)

Peringatan: Permintaan perubahan 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 dalam kontak yang akan diperbarui guna memastikan kontak tidak berubah sejak terakhir kali Anda membaca. Gunakan kode berikut:

Protocol

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 operasi tulis penting (Pembuatan dan Update Kontak)
• 1 Penulisan Kontak Harian (Total)

Peringatan: Permintaan perubahan 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:

Protocol

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 penulisan (Penghapusan Kontak dan Penulisan Grup Kontak)

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

Membuat kontak baru secara massal

Untuk membuat kontak baru sekaligus, gunakan kode berikut:

Protocol

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 (Pembacaan Kontak dan Profil)
• 6 Permintaan operasi tulis penting (Pembuatan dan Update Kontak)
• 200 Penulisan Kontak Harian (Total)

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

Memperbarui massal kontak yang ada

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

Protocol

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 (Pembacaan Kontak dan Profil)
• 6 Permintaan operasi tulis penting (Pembuatan dan Update Kontak)
• 200 Penulisan Kontak Harian (Total)

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

Menghapus banyak kontak yang ada sekaligus

Untuk menghapus banyak kontak yang ada sekaligus, gunakan kode berikut:

Protocol

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 Penulisan Grup Kontak)

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