Trang này được dịch bởi Cloud Translation API.

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

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

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

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

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)

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

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

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)

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