Đọ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.

Lưu ý quan trọng: Bạn chỉ có thể sửa đổi những người dựa trên danh bạ. Bạn không thể sửa đổi hồ sơ được đọc bằng tên tài nguyên "people/me" hoặc bằng mã tài khoản.

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

Lưu ý: Hoạt động ghi có thể có độ trễ truyền tải vài phút đối với các yêu cầu đồng bộ hoá. Tính năng đồng bộ hoá tăng dần không dành cho các trường hợp sử dụng đọc sau khi ghi.

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

Lưu ý quan trọng: Tính năng Tìm kiếm sử dụng bộ nhớ đệm tải từng phần được cập nhật sau khi bạn yêu cầu. Trước tiên, ứng dụng phải gửi yêu cầu tìm kiếm khởi động với một truy vấn trống để đảm bảo bộ nhớ đệm có dữ liệu mới nhất.

Lưu ý: Tính năng Tìm kiếm thực hiện việc so khớp tiền tố của truy vấn với các trường trên một người. Ví dụ: một người có tên "foo name" sẽ khớp với các cụm từ tìm kiếm như "f", "fo", "foo", "foo n", "nam", v.v., nhưng không khớp với "oo n".

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ảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.

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": "[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();

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ảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.

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

Cảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.

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ảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.

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": "[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();

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ảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.

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

Cảnh báo: Thay đổi yêu cầu cho cùng một người dùng nên được gửi tuần tự để tránh độ trễ và lỗi tăng lên.