อ่านและจัดการรายชื่อติดต่อ

หลังจากทำตามขั้นตอนในเตรียมพร้อมใช้ People API เสร็จแล้ว คุณก็พร้อมที่จะอ่านและจัดการรายชื่อติดต่อ

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีส่งคําของ่ายๆ 2-3 รายการ ดูรายการวิธีการทั้งหมดได้ในเอกสารอ้างอิง

สำคัญ: คุณแก้ไขได้เฉพาะบุคคลตามรายชื่อติดต่อเท่านั้น บุคคลตามโปรไฟล์ที่อ่านโดยใช้ ชื่อทรัพยากร "people/me" หรือ รหัสบัญชี จะแก้ไขไม่ได้

แสดงรายชื่อติดต่อของผู้ใช้

หากต้องการดูรายชื่อบุคคลในรายชื่อติดต่อของผู้ใช้ ให้ใช้โค้ดต่อไปนี้

โปรโตคอลJavaPythonPHP.NET

GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

ListConnectionsResponse response = peopleService.people().connections().list("people/me")
    .setPersonFields("names,emailAddresses")
    .execute();
List<Person> people = response.getConnections();

people = people_service.people().connections()
    .list('people/me', personFields='names,emailAddresses')

$people = $people_service->people_connections->listPeopleConnections(
    'people/me', array('personFields' => 'names,emailAddresses'));

PeopleResource.ConnectionsResource.ListRequest peopleRequest =
    peopleService.People.Connections.List("people/me");
peopleRequest.PersonFields = "names,emailAddresses";
ListConnectionsResponse response = peopleRequest.Execute();
IList<Person> people = response.Connections;

แสดงรายชื่อติดต่อของผู้ใช้ที่มีการเปลี่ยนแปลง

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

หมายเหตุ: การเขียนอาจมีความล่าช้าในการนำไปใช้หลายนาทีสำหรับคำขอซิงค์ การซิงค์แบบเพิ่มไม่ได้มีไว้สำหรับ Use Case การอ่านหลังจากเขียน

ดูรายละเอียดเพิ่มเติมเกี่ยวกับลักษณะการซิงค์ได้ที่ ListConnections

ค้นหารายชื่อติดต่อของผู้ใช้

หากต้องการค้นหารายชื่อติดต่อทั้งหมดของผู้ใช้ ให้ใช้โค้ดต่อไปนี้

โปรโตคอลJava

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

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

สำคัญ: Search ใช้แคชแบบ Lazy ที่อัปเดตหลังจากได้รับคำขอ ลูกค้าควรส่งคำขอการค้นหาเพื่อเตรียมความพร้อมก่อนใช้งานด้วยคำค้นหาว่างก่อนเพื่อให้แน่ใจว่าแคชมีข้อมูลล่าสุด

หมายเหตุ: Search จะจับคู่คำนำหน้าของคำค้นหากับช่องในบุคคล เช่น บุคคลที่มีชื่อ "foo name" จะจับคู่กับคำค้นหา เช่น "f", "fo", "foo", "foo n", "nam" ฯลฯ แต่ไม่จับคู่กับ "oo n"

สร้างรายชื่อติดต่อใหม่

หากต้องการสร้างรายชื่อติดต่อใหม่ ให้ใช้รหัสต่อไปนี้

โปรโตคอลJava

POST /v1/people:createContact HTTP/1.1
Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] }
Host: people.googleapis.com

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

การใช้โควต้าต่อคำขอ

• คำขออ่านที่สำคัญ 1 รายการ (การอ่านรายชื่อติดต่อและโปรไฟล์)
• คําขอเขียนสําคัญ 1 รายการ (การสร้างและการอัปเดตรายชื่อติดต่อ)
• การเขียนรายชื่อติดต่อรายวัน 1 รายการ (ทั้งหมด)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ

อัปเดตรายชื่อติดต่อที่มีอยู่

หากต้องการอัปเดตรายชื่อติดต่อที่มีอยู่ คุณต้องใส่ช่อง person.metadata.sources.etag ในบุคคลเพื่อให้ระบบอัปเดตรายชื่อติดต่อ ตรวจสอบว่ารายชื่อติดต่อนั้นไม่มีการเปลี่ยนแปลงนับตั้งแต่ที่คุณอ่านครั้งล่าสุด ใช้โค้ดต่อไปนี้

โปรโตคอลJava

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1
Body: {
    "resourceName": "resource_name",
    "etag": "etag",
    "emailAddresses": [{ "value": "[e-mail]" }],
}
Host: people.googleapis.com

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

การใช้โควต้าต่อคำขอ

• คำขออ่านที่สำคัญ 1 รายการ (การอ่านรายชื่อติดต่อและโปรไฟล์)
• คําขอเขียนสําคัญ 1 รายการ (การสร้างและการอัปเดตรายชื่อติดต่อ)
• การเขียนรายชื่อติดต่อรายวัน 1 รายการ (ทั้งหมด)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ

ลบรายชื่อติดต่อที่มีอยู่

หากต้องการลบรายชื่อติดต่อที่มีอยู่ ให้ใช้โค้ดต่อไปนี้

โปรโตคอลJava

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

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

การใช้โควต้าต่อคำขอ

• คำขอเขียน 1 รายการ (การลบรายชื่อติดต่อและการเขียนกลุ่มรายชื่อติดต่อ)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ

สร้างผู้ติดต่อใหม่ทีละหลายรายการ

หากต้องการสร้างผู้ติดต่อใหม่ทีละหลายรายการ ให้ใช้โค้ดต่อไปนี้

โปรโตคอลJava

POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1
Body: {
  "contacts": [
    {
      "contactPerson": {
        "names": [
          {
            "givenName": "John",
            "familyName": "Doe"
          }
        ]
      }
    }
  ]
}
Host: people.googleapis.com

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

การใช้โควต้าต่อคำขอ

• คำขออ่านที่สำคัญ 6 รายการ (การอ่านรายชื่อติดต่อและโปรไฟล์)
• คําขอเขียนสําคัญ 6 รายการ (การสร้างและการอัปเดตรายชื่อติดต่อ)
• การเขียนรายชื่อติดต่อรายวัน 200 รายการ (ทั้งหมด)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ

อัปเดตรายชื่อติดต่อที่มีอยู่หลายรายการพร้อมกัน

หากต้องการอัปเดตรายชื่อติดต่อที่มีอยู่ คุณต้องใส่ช่อง person.metadata.sources.etag ในแต่ละบุคคลเพื่อให้ระบบอัปเดตรายชื่อติดต่อ และตรวจสอบว่ารายชื่อติดต่อนั้นไม่มีการเปลี่ยนแปลงนับตั้งแต่ที่คุณอ่านครั้งล่าสุด ใช้โค้ดต่อไปนี้

โปรโตคอลJava

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

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

การใช้โควต้าต่อคำขอ

• คำขออ่านที่สำคัญ 6 รายการ (การอ่านรายชื่อติดต่อและโปรไฟล์)
• คําขอเขียนสําคัญ 6 รายการ (การสร้างและการอัปเดตรายชื่อติดต่อ)
• การเขียนรายชื่อติดต่อรายวัน 200 รายการ (ทั้งหมด)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ

ลบรายชื่อติดต่อที่มีอยู่ทีละหลายรายการ

หากต้องการ ลบรายชื่อติดต่อที่มีอยู่ทีละหลายรายการ ให้ใช้โค้ดต่อไปนี้

โปรโตคอลJava

POST /v1/people:batchDeleteContacts HTTP/1.1
Body: {"resource_names": ["resource_name"]}
Host: people.googleapis.com

BatchDeleteContactsRequest request = new BatchDeleteContactsRequest();

request.setResourceNames(ImmutableList.of(resource_name));

peopleService.people().batchDeleteContacts(request).execute();

การใช้โควต้าต่อคำขอ

• คำขอเขียน 10 รายการ (การลบรายชื่อติดต่อและการเขียนกลุ่มรายชื่อติดต่อ)

คำเตือน: คุณควรส่งคำขอเปลี่ยนรูปแบบสำหรับผู้ใช้รายเดียวกันตามลำดับเพื่อหลีกเลี่ยงการเพิ่มขึ้นของเวลาในการตอบสนองและการดำเนินการที่ไม่สำเร็จ