연락처 읽기 및 관리

People API 사용 준비의 단계를 완료하면 주소록을 읽고 관리할 수 있습니다.

다음 코드 샘플은 몇 가지 간단한 요청을 보내는 방법을 보여줍니다. 메서드의 전체 목록은 참조 문서를 참고하세요.

중요: 연락처 기반 사용자만 수정할 수 있습니다. 리소스 이름 "people/me"을 사용하거나 계정 ID를 사용하여 읽은 프로필 기반 사용자는 수정할 수 없습니다.

사용자의 연락처 표시

사용자의 연락처에 있는 사용자 목록을 가져오려면 다음 코드를 사용하세요.

프로토콜

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

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;

변경된 사용자의 연락처를 나열합니다.

자바

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

참고: 동기화 요청의 경우 쓰기에 몇 분의 전파 지연이 발생할 수 있습니다. 증분 동기화는 쓰기 후 읽기 사용 사례에 적합하지 않습니다.

동기화 동작에 관한 자세한 내용은 ListConnections를 참고하세요.

사용자의 연락처 검색

사용자의 모든 연락처를 검색하려면 다음 코드를 사용합니다.

프로토콜

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

중요: 검색은 요청 후에 업데이트되는 지연 캐시를 사용합니다. 클라이언트는 먼저 빈 쿼리가 포함된 준비 검색 요청을 전송하여 캐시에 최신 데이터가 있는지 확인해야 합니다.

참고: 검색은 쿼리의 접두사를 사용자의 필드와 일치시킵니다. 예를 들어 이름이 'foo name'인 사용자는 'f', 'fo', 'foo', 'foo n', 'nam'과 같은 검색어와 일치하지만 'oo n'과는 일치하지 않습니다.

새 연락처 만들기

새 연락처를 만들려면 다음 코드를 사용하세요.

프로토콜

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 필드를 포함해야 합니다. 그러면 마지막 읽기 이후 연락처가 변경되지 않았는지 확인할 수 있습니다. 다음 코드를 사용합니다.

프로토콜

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회

경고: 지연 시간과 오류가 증가하지 않도록 동일한 사용자에 대한 변경 요청을 순차적으로 전송해야 합니다.

기존 연락처 삭제하기

기존 연락처를 삭제하려면 다음 코드를 사용하세요.

프로토콜

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

자바

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

요청당 할당량 사용량

• 1개의 쓰기 요청 (연락처 삭제 및 연락처 그룹 쓰기)

경고: 지연 시간과 오류가 증가하지 않도록 동일한 사용자에 대한 변경 요청을 순차적으로 전송해야 합니다.

새 연락처 일괄 생성

새 연락처를 일괄 생성하려면 다음 코드를 사용하세요.

프로토콜

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 필드를 포함하여 마지막 읽기 이후 연락처가 변경되지 않았는지 확인해야 합니다. 다음 코드를 사용합니다.

프로토콜

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회 (총)

경고: 지연 시간과 오류가 증가하지 않도록 동일한 사용자에 대한 변경 요청을 순차적으로 전송해야 합니다.

기존 연락처 일괄 삭제

기존 연락처를 일괄 삭제하려면 다음 코드를 사용하세요.

프로토콜

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개 (연락처 삭제 및 연락처 그룹 쓰기)

경고: 지연 시간과 오류가 증가하지 않도록 동일한 사용자에 대한 변경 요청을 순차적으로 전송해야 합니다.