소개
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
People API를 사용하면 다음과 같은 작업을 할 수 있습니다.
- 인증된 사용자의 연락처 읽기 및 관리
- 인증된 사용자의 '기타 연락처'를 읽고 복사합니다.
- 인증된 사용자 및 사용자 연락처의 프로필 정보를 읽습니다.
- 도메인 프로필 및 연락처 읽기
예를 들어 인증된 사용자인 젠의 비공개 연락처에 파비안과 란지스가 있다고 가정해 보겠습니다. 앱에서 people.connections.list를 호출하여 연결 목록을 읽으면 젠에게는 앱에 목록 액세스 권한을 부여하라는 동의 화면이 표시됩니다. 젠이 동의하면 앱은 Fabian과 Ranjith를 위한 person resources가 포함된 목록을 읽습니다.
앱이 특정 사람의 정보가 필요한 경우 people.get를 호출하고 리소스 이름을 전달하여 그 사람의 person resource를 가져올 수 있습니다.
앱은 people.createContact를 사용하여 새 연락처를 만들어 연락처를 관리하고 people.updateContact를 사용하여 people.connections.list에서 읽은 기존 연락처를 업데이트하며 people.deleteContact를 사용하여 연락처를 삭제할 수도 있습니다.
Google Workspace 사용자는 people.listDirectoryPeople를 사용하여 디렉터리 도메인 프로필과 도메인 연락처를 나열하거나 people.searchDirectoryPeople을 사용하여 검색할 수도 있습니다.
People API가 읽는 사용자 정보는 다음 조건에 따라 다양한 소스에서 병합됩니다.
병합된 개인 데이터 이해
사람에 대한 데이터는 한 가지 기본 소스 유형에서 파생됩니다. 인증된 이메일 주소, 전화번호 또는 프로필 URL을 통해 소스가 연결된 경우 다른 소스의 데이터는 이 데이터와 병합됩니다. 사람을 구성하는 방법은 다음과 같습니다.
연락처 기반의 사용자만 변형 엔드포인트로 수정할 수 있습니다. 프로필 및 도메인 연락처 변형은 지원되지 않습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eThe People API allows reading and managing the authenticated user's contacts, including private contacts and "Other contacts".\u003c/p\u003e\n"],["\u003cp\u003eUsers can access profile information for authenticated users and their contacts, including public Google profile data and, when permitted, Google Workspace domain profile data.\u003c/p\u003e\n"],["\u003cp\u003eThe API facilitates managing contacts by creating, updating, and deleting contacts through specific endpoints.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Workspace users can utilize the API to list and search domain profiles and domain contacts.\u003c/p\u003e\n"],["\u003cp\u003eThe People API merges data from various sources like public profiles, private profiles, contacts, and domain information based on verified email addresses, phone numbers, or profile URLs.\u003c/p\u003e\n"]]],["The People API enables reading and managing authenticated user contacts, \"Other contacts,\" and profile information, including domain profiles. Apps can list connections via `people.connections.list`, retrieve specific person data using `people.get`, create contacts with `people.createContact`, update contacts with `people.updateContact`, and delete contacts via `people.deleteContact`. Google Workspace users can access domain contacts using `people.listDirectoryPeople` or `people.searchDirectoryPeople`. The data is merged from sources like public profiles, domain data, and private information, depending on user consent and scopes granted.\n"],null,["# Introduction\n\nThe People API lets you:\n\n- Read and manage the authenticated user's [Contacts](https://contacts.google.com)\n- Read and copy the authenticated user's [\"Other contacts\"](https://contacts.google.com/other)\n- Read profile information for authenticated users and their contacts\n- Read domain profiles and contacts\n\nFor example, suppose that the authenticated user, Jen, has Fabian and Ranjith in\nher private contacts. When your app calls\n[`people.connections.list`](/people/api/rest/v1/people.connections/list) to read a\nlist of her connections, Jen is presented with a consent screen asking to give\nthe app access to the list. If Jen consents, the app reads a list containing\n[`person resources`](/people/api/rest/v1/people) for Fabian and Ranjith.\n\nIf the app needs information for a specific person, it can then call\n[`people.get`](/people/api/rest/v1/people/get), passing in a resource name, to get\nthe [`person resource`](/people/api/rest/v1/people) for that person.\n\nThe app can also manage contacts by creating new contacts using\n[`people.createContact`](/people/api/rest/v1/people/createContact), update existing\ncontacts it has read from\n[`people.connections.list`](/people/api/rest/v1/people.connections/list) using\n[`people.updateContact`](/people/api/rest/v1/people/updateContact), and delete contacts\nusing [`people.deleteContact`](/people/api/rest/v1/people/deleteContact).\n\nGoogle Workspace users can also list their directory domain profiles and domain\ncontacts using\n[`people.listDirectoryPeople`](/people/api/rest/v1/people/listDirectoryPeople) or search\nthem using\n[`people.searchDirectoryPeople`](/people/api/rest/v1/people/searchDirectoryPeople).\n\nA merged view of people information\n-----------------------------------\n\nThe people information that the People API reads is merged from various\nsources, depending on the following conditions:\n\n| Source | Condition |\n|------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Public Google profile data | Always. |\n| Google Workspace domain profile data | The domain admin has [enabled external contact and profile sharing](https://support.google.com/a/answer/6343701) of domain-scoped data and the [`directory.readonly` scope](/people/v1/how-tos/authorizing#directory) has been granted |\n| The authenticated user's private profile information | One of the [`profile` scopes](/people/v1/how-tos/authorizing#OAuth2Authorizing) has been granted. |\n| The authenticated user's contacts | The [`contacts` scope](/people/v1/how-tos/authorizing#contacts) has been granted. |\n\nUnderstanding Merged Person Data\n--------------------------------\n\nThe data for a person is derived from one main source type. Data from other\nsources is merged with this data if the sources are connected through verified\nemail addresses, phone numbers, or profile URLs. These are the ways a person may\nbe composed:\n\n| Main Source | Contacts | Profiles | Google Workspace Domain Profiles | Google Workspace Domain Contacts | Usage |\n|----------------|----------|----------|----------------------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Contact | 1 | 0+ | 0+ | 0+ | Returned for most endpoints |\n| Profile | 0+ | 1 | 0 or 1 | 0 | Returned in [`people.get`](/people/api/rest/v1/people/get) when it is used to get the person [for the signed-in user](/people/v1/profiles#get_the_person_for_the_authenticated_user) or get a person for [another user's Google Account](/people/v1/read-people#get_the_person_for_a_google_account_id). |\n| Domain Contact | 0+ | 0 | 0 | 1 | Returned in [`people.listDirectoryPeople`](/people/api/rest/v1/people/listDirectoryPeople) or [`people.searchDirectoryPeople`](/people/api/rest/v1/people/searchDirectoryPeople). |\n\nOnly contact based people can be modified by mutation endpoints. Profile and\ndomain contact mutations are not supported."]]
