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

Sau khi hoàn tất các bước trong phần Chuẩn bị sử dụng API People, bạn đã sẵn sàng đọc và quản lý danh bạ.

Các mã mẫu sau đây minh hoạ cách gửi một vài yêu cầu đơn giản. Để xem 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ạ. Không thể sửa đổi người dùng dựa trên 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

Để lấy danh sách người dùng 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')

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;

Liệt kê những người liên hệ đã 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 ý: Các yêu cầu đồng bộ hoá có thể bị trễ truyền tải vài phút đối với các yêu cầu ghi. 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.

Xem thêm thông tin chi tiết 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ả danh bạ 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ìm kiếm sử dụng bộ nhớ đệm tải lười được cập nhật sau một yêu cầu. Trước tiên, ứng dụng phải gửi một yêu cầu tìm kiếm khởi động bằng một cụm từ tìm kiếm trống để đảm bảo rằng bộ nhớ đệm có dữ liệu mới nhất.

Lưu ý: Tính năng Tìm kiếm sẽ so khớp tiền tố của cụm từ tìm kiếm 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();

Mức sử dụng hạn mức theo yêu cầu

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

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

Cập nhật thông tin liên hệ hiện có

Để cập nhật một người liên hệ hiện có, bạn phải thêm trường person.metadata.sources.etag vào người liên hệ cần cập nhật để đảm bảo người liên hệ đó không thay đổi kể từ lần đọc gần đây nhất. Sử 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();

Mức sử dụng hạn mức theo yêu cầu

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

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

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

Để xoá một người liên hệ hiện có, hãy sử 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();

Mức sử dụng hạn mức theo yêu cầu

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

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

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

Để tạo hàng loạt người 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();

Mức sử dụng hạn mức theo yêu cầu

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

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

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

Để cập nhật một người 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 người liên hệ đó nhằm đảm bảo người liên hệ đó không thay đổi kể từ lần đọc gần đây nhất. Sử 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();

Mức sử dụng hạn mức theo yêu cầu

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

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

Xoá hàng loạt người liên hệ hiện có

Để xoá hàng loạt danh bạ hiện có, hãy sử 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();

Mức sử dụng hạn mức theo yêu cầu

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

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