Đọc và quản lý danh bạ

Sau khi hoàn tất các bước trong bài viết Chuẩn bị sẵn sàng để sử dụng API Mọi người, bạn có thể đọc và quản lý danh bạ.

Các mã mẫu sau đây minh hoạ cách gửi một số yêu cầu đơn giản. Để biết danh sách đầy đủ các phương thức, hãy xem tài liệu tham khảo.

Liệt kê danh bạ của người dùng

Để nhận danh sách người liên hệ trong danh bạ của người dùng, hãy sử dụng mã sau:

Giao thức

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')

1.199

$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;

Liệt kê danh bạ đã thay đổi của người dùng

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

Thông tin chi tiết khác về hành vi đồng bộ hoá tại ListConnections.

Tìm kiếm danh bạ của người dùng

Để tìm kiếm tất cả thông tin liên hệ của người dùng, hãy sử dụng mã sau:

Giao thức

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

Tạo địa chỉ liên hệ mới

Để tạo một người liên hệ mới, hãy sử dụng mã sau:

Giao thức

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

Sử dụng hạn mức cho mỗi yêu cầu

  • 1 yêu cầu đọc quan trọng (Đọc liên hệ và hồ sơ)
  • 1 yêu cầu ghi quan trọng (Tạo và cập nhật liên hệ)
  • 1 lượt ghi liên hệ hằng ngày (Tổng cộng)

Cập nhật địa chỉ liên hệ hiện có

Để cập nhật một mục liên hệ hiện có, bạn phải thêm trường person.metadata.sources.etag vào mục liên hệ để cập nhật mục liên hệ, nhằm đảm bảo mục liên hệ đó chưa thay đổi kể từ lần đọc gần đây nhất. Hãy dùng mã sau:

Giao thức

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1
Body: {
    "resourceName": "resource_name",
    "etag": "etag",
    "emailAddresses": [{ "value": "john.doe@gmail.com" }],
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

List<EmailAddress> emailAddresses = new ArrayList<>();
emailAddresses.add(new EmailAddress().setValue("john.doe@gmail.com"));
contactToUpdate.setEmailAddresses(emailAddresses);

Person updatedContact = peopleService.people()
    .updateContact(contactToUpdate.getResourceName(), contactToUpdate)
    .setUpdatePersonFields("emailAddresses")
    .execute();

Sử dụng hạn mức cho mỗi yêu cầu

  • 1 yêu cầu đọc quan trọng (Đọc liên hệ và hồ sơ)
  • 1 yêu cầu ghi quan trọng (Tạo và cập nhật liên hệ)
  • 1 lượt ghi liên hệ hằng ngày (Tổng cộng)

Xoá người liên hệ hiện có

Để xoá một người liên hệ hiện có, hãy dùng mã sau:

Giao thức

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

Java

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

Sử dụng hạn mức cho mỗi yêu cầu

  • 1 yêu cầu ghi (Xoá liên hệ và Ghi nhóm liên hệ)

Tạo hàng loạt người liên hệ mới

Để tạo hàng loạt địa chỉ liên hệ mới, hãy sử dụng mã sau:

Giao thức

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

Sử dụng hạn mức cho mỗi yêu cầu

  • 6 yêu cầu đọc quan trọng (Đọc liên hệ và Hồ sơ)
  • 6 yêu cầu ghi quan trọng (Tạo và cập nhật liên hệ)
  • 200 lượt ghi liên hệ hằng ngày (Tổng cộng)

Cập nhật hàng loạt địa chỉ liên hệ hiện tại

Để cập nhật một mục liên hệ hiện có, bạn phải thêm trường person.metadata.sources.etag vào mỗi người để cập nhật mục liên hệ, nhằm đảm bảo mục liên hệ đó chưa thay đổi kể từ lần đọc gần đây nhất. Hãy dùng mã sau:

Giao thức

POST /v1/people:batchUpdateContacts?updateMask=names&readMask=names,emailAddresses HTTP/1.1
Body: {
  "contacts": {
    "resource_name": {
      "emailAddresses": [
        {
          "value": "john.doe@gmail.com"
        }
      ]
      "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();

Sử dụng hạn mức cho mỗi yêu cầu

  • 6 yêu cầu đọc quan trọng (Đọc liên hệ và Hồ sơ)
  • 6 yêu cầu ghi quan trọng (Tạo và cập nhật liên hệ)
  • 200 lượt ghi liên hệ hằng ngày (Tổng cộng)

Xóa hàng loạt địa chỉ liên hệ hiện có

Để xoá hàng loạt người liên hệ hiện có, hãy dùng mã sau:

Giao thức

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

Sử dụng hạn mức cho mỗi yêu cầu

  • 10 yêu cầu ghi (Xoá liên hệ và Ghi nhóm liên hệ)