CardDAV 프로토콜로 연락처 관리
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google의 CardDAV 프로토콜을 사용하여 연락처를 보고 관리할 수 있습니다.
연락처가 사용자의 Google 계정에 저장됩니다. 대부분의 Google 서비스에는
연락처 목록에 액세스할 수 없습니다. 클라이언트 애플리케이션은 CardDAV API를 사용하여 새 연락처를 만들고, 기존 연락처를 수정 또는 삭제하고, 특정 기준과 일치하는 연락처를 쿼리할 수 있습니다.
사양
전체 사양은 구현되지 않았지만 Apple iOS™ 연락처 및 macOS와 같은 많은 클라이언트는 올바르게 상호 운용되어야 합니다.
관련 사양별로 Google의 CardDAV 지원은 다음과 같습니다.
Google의 CardDAV에는 OAuth 2.0이 필요합니다.
Google의 CardDAV 인터페이스에는 OAuth 2.0이 필요합니다. OAuth 2.0을 사용하여 Google API에 액세스하는 방법에 관한 자세한 내용은 아래 링크된 문서를 참고하세요.
Google의 CardDAV 서버에 연결
CardDAV 프로토콜을 사용하면 주소록과 연락처 리소스를 검색할 수 있습니다.
URI. URI는 언제든지 변경될 수 있으므로 URI를 하드코딩해서는 안 됩니다.
클라이언트 애플리케이션은 HTTPS를 사용해야 하며 사용자의 Google 계정에 OAuth 2.0 인증을 제공해야 합니다. CardDAV 서버는 Google 계정의 OAuth 2.0 인증과 함께 HTTPS를 통해 도착하고 애플리케이션이 DevConsole에 등록되어 있지 않으면 요청을 인증하지 않습니다. 기본 인증 또는
이메일/비밀번호가 Google 계정과 일치하지 않으면 HTTP 요청이
401 Unauthorized 응답 코드입니다.
CardDAV를 사용하려면 클라이언트 프로그램이 다음에서 HTTP PROPFIND를 실행하여 처음에 표준 검색 경로에 연결해야 합니다.
https://www.googleapis.com/.well-known/carddav
주소록 리소스로 리디렉션(HTTP 301)되면 클라이언트 프로그램은 주소록 리소스에 대해 PROPFIND를 실행하여 DAV:current-user-principal, DAV:principal-URL, addressbook-home-set 속성을 찾을 수 있습니다. 그러면 클라이언트 프로그램은
addressbook-home-set에서 PROPFIND를 수행하고
addressbook 및 collection 리소스. 이 프로세스에 대한 자세한 설명은 이 문서의 범위를 벗어납니다. 자세한 내용은
rfc6352를 참고하세요.
잘 알려진 URI의 PROPFIND를 통해 HTTP 301 응답으로 반환된 리디렉션 경로는 rfc6764에 따라 영구적으로 캐시되어서는 안 됩니다. 기기는 잘 알려진 URI 검색을 주기적으로 다시 시도하여 캐시된 경로가 여전히 최신 상태인지 확인하고 경로가 변경되면 다시 동기화해야 합니다. 2~4주마다 업데이트하는 것이 좋습니다.
리소스
CardDAV는 REST 개념을 사용합니다. 클라이언트 애플리케이션은
리소스 ID입니다. 개발자가 다음 섹션의 개념을 이해하는 데 도움이 되도록 현재 URI 구조가 여기에 지정되어 있습니다. 구조는
하드코딩되어서는 안 됩니다. 대신 리소스는 RFC에 따라 검색되어야 합니다.
- 주 구성원
<ph type="x-smartling-placeholder">
</ph>
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- 주소록
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- 문의
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
다음은 지원되는 작업에 대한 일반적인 설명입니다. 개발자는 관련 RFC에서 세부정보를 찾아야 합니다. 요청과 응답은
대부분 XML로 인코딩되어 있습니다. 이것은 클라이언트가 사용하는 기본 작업이며
동기화용 애플리케이션:
- CTag 사용
<ph type="x-smartling-placeholder">
</ph>
- 클라이언트 프로그램은 주소록 리소스의
getctag PROPFIND 요청을 사용하여 서버에서 연락처가 변경되었는지, 따라서 동기화가 필요한지 확인합니다. 이 속성의 값입니다.
연락처가 변경되면 변경됩니다. 클라이언트 애플리케이션
이 값을 저장하고 초기 동기화 시에만 사용해야 하며
sync-token가 무효화될 때 대체를 지원합니다. getctag 속성을 주기적으로 폴링하면 제한이 적용됩니다.
- 동기화 토큰 사용
<ph type="x-smartling-placeholder">
</ph>
- 클라이언트 프로그램은 주소록의
sync-token PROPFIND 요청을 사용하여 현재 상태를 나타내는 sync-token를 가져옵니다. 고객
애플리케이션은 이 값을 저장하고 주기적인 sync-collection를 실행해야 합니다.
마지막 요청 이후 변경사항 확인 요청 REPORT건
sync-token입니다. 발급된 토큰은 29일 동안 유효하며, REPORT
응답에는 새로운 sync-token가 포함됩니다.
- ETag 사용
<ph type="x-smartling-placeholder">
</ph>
- 클라이언트 애플리케이션은 주소록 리소스에
getetag PROPFIND 요청을 실행합니다(DEPTH 헤더가 DEPTH_1임). 각 연락처의 ETag 값을 유지하여 클라이언트 프로그램은 ETag가 변경된 연락처의 값을 요청할 수 있습니다.
- 연락처 가져오기
- 클라이언트 애플리케이션은
addressbook-multiget REPORT 요청. 연락처 URI 목록이 주어지면
보고서는 요청된 모든 연락처를 VCard 3.0 값으로 반환합니다. 각
항목에는 연락처에 대한 ETag가 포함됩니다.
- 연락처 삽입
- 클라이언트 애플리케이션은 VCard 3.0 형식의 새 연락처가 포함된
POST 요청을 실행합니다. 응답에는 새 연락처의 ID가 포함됩니다.
- 연락처 업데이트
<ph type="x-smartling-placeholder">
</ph>
- 클라이언트 애플리케이션은
PUT 요청을 통해 업데이트된 연락처로
VCard 3.0 형식 연락처가 이미 주소록에 있는 경우 연락처가 업데이트됩니다.
- 클라이언트 애플리케이션에는 다음과 같은
If-Match 헤더가 포함되어야 합니다.
연락처의 현재 알려진 ETag입니다. 그러면 서버의 현재 ETag가 클라이언트 프로그램에서 전송한 ETag와 다른 경우 서버는 PUT 요청(HTTP 412 포함)을 거부합니다. 이렇게 하면 업데이트를 낙관적으로 직렬화할 수 있습니다.
- 연락처 삭제
<ph type="x-smartling-placeholder">
</ph>
- 클라이언트 애플리케이션은
DELETE 요청을 실행하여 연락처를 삭제합니다.
연락처 URI와 대조합니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-25(UTC)
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eGoogle Contacts can be accessed and managed using the CardDAV protocol, enabling client applications to create, edit, delete, and query contacts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV implementation requires OAuth 2.0 for authentication and HTTPS for secure connections.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should discover resource URIs dynamically instead of hardcoding them, as they are subject to change.\u003c/p\u003e\n"],["\u003cp\u003eContact synchronization can be achieved using CTag, sync-token, or ETags to efficiently track and update changes.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV utilizes VCard 3.0 for encoding contact data.\u003c/p\u003e\n"]]],["Google's CardDAV protocol allows managing contacts stored in a Google Account. Client applications can create, edit, delete, and query contacts using the CardDAV API. Key actions include using `PROPFIND` for discovery and obtaining `sync-token` and `getctag` for synchronization. Retrieving contacts is done with `addressbook-multiget REPORT`, while inserting, updating, and deleting contacts utilize `POST`, `PUT` (with `If-Match`), and `DELETE` requests, respectively. Authentication requires HTTPS and OAuth 2.0, and VCard 3.0 is the contact encoding format.\n"],null,["# Manage contacts with the CardDAV protocol\n\nYou can view and manage your contacts using Google's CardDAV protocol.\n\nContacts are stored in the user's Google Account; most Google services have\naccess to the contact list. Your client application can use the CardDAV API to\ncreate new contacts, edit or delete existing contacts, and query for contacts\nthat match particular criteria.\n\nSpecifications\n--------------\n\nThe full specification is not implemented, but many clients such as\n[Apple iOS™ Contacts](https://support.google.com/contacts/answer/2753077?co=GENIE.Platform%3DiOS)\nand macOS should interoperate correctly.\n\nFor each relevant specification, Google's CardDAV support is as follows:\n\n- [rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)](https://tools.ietf.org/html/rfc2518)\n - Supports the HTTP methods `GET`, `PUT`, `DELETE`, `OPTIONS`, and `PROPFIND`.\n - Does *not* support the HTTP methods `LOCK`, `UNLOCK`, `COPY`, `MOVE`, or `MKCOL`.\n - Does *not* support arbitrary (user-defined) WebDAV properties.\n - Does *not* support WebDAV Access Control (rfc3744).\n- [rfc5995: Using POST to Add Members to WebDAV Collections](https://tools.ietf.org/html/rfc5995)\n - Supports creating new contacts without specifying an ID.\n- [rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and\n Versioning (WebDAV)](https://tools.ietf.org/html/rfc6352)\n - Supports the HTTP method `REPORT`, but not all defined reports are implemented.\n - Supports providing a principal collection and a contacts collection.\n- [rfc6578: Collection Synchronization for WebDAV](https://tools.ietf.org/html/rfc6578)\n - Client applications must switch to this mode of operation after the initial sync.\n- [rfc6749: The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)\n - Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use [HTTPS](https://en.wikipedia.org/wiki/HTTPS).\n- [rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)](https://tools.ietf.org/html/rfc6764)\n - Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.\n- Supports [caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV](https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt), which is shared between the CardDAV and CalDAV specifications. The contacts `ctag` is like a resource `ETag`; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.\n- Google uses VCard 3.0 as the contact encoding format. See: [rfc6350: VCard 3.0](https://tools.ietf.org/html/rfc6350).\n\nGoogle's CardDAV requires OAuth 2.0\n-----------------------------------\n\nGoogle's CardDAV interface requires OAuth 2.0. Refer to the linked\ndocumentation below for information on using OAuth 2.0 to access Google APIs:\n\n- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)\n- [Using OAuth 2.0 for Installed Applications](https://developers.google.com/identity/protocols/oauth2/native-app)\n\nConnecting to Google's CardDAV server\n-------------------------------------\n\nThe CardDAV protocol allows discovery of the address book and contact resources\nURIs. You must not hardcode any URI as they could change at any time.\n\nClient applications must use HTTPS, and `OAuth 2.0` authentication must be\nprovided for the user's Google account. The CardDAV server will not\nauthenticate a request unless it arrives over HTTPS with OAuth 2.0\nauthentication of a Google account, and your application is registered on\nDevConsole. Any attempt to connect over HTTP with Basic authentication or with\nan email/password that doesn't match a Google account results in an HTTP\n`401 Unauthorized` response code.\n\nTo use CardDAV, your client program must initially connect to the canonical\ndiscovery path by performing an HTTP `PROPFIND` on: \n\n https://www.googleapis.com/.well-known/carddav\n\nOnce redirected (`HTTP 301`) to an Address Book Resource, your client program\ncan then perform a `PROPFIND` on it to discover the\n`DAV:current-user-principal`, `DAV:principal-URL`, and `addressbook-home-set`\nproperties. Your client program can then discover the principal address book by\nperforming a `PROPFIND` on the `addressbook-home-set` and looking for the\n`addressbook` and `collection` resources. A full description of this process\nis beyond the scope of this document. See\n[rfc6352](https://tools.ietf.org/html/rfc6352) for more details.\n\nThe redirect path returned in the `HTTP 301` response through a `PROPFIND` on\nthe well-known URI must **not** be permanently cached (as per\n[rfc6764](https://tools.ietf.org/html/rfc6764)). Devices should retry well-known\nURI discovery periodically to verify if the cached path is still up to date and\nresync if the path ever changes. Google recommends a rate of every 2-4 weeks.\n\nResources\n---------\n\nCardDAV uses REST concepts. Client applications act on resources that are\ndesignated by their URIs. The current URI structure is specified here to help\ndevelopers understand the concepts in the following section. The structure may\nchange and must not be hardcoded. Rather, the resources should be discovered\naccording to the RFC.\n\n1. **Principal**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e\n2. **Home Set**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists\n3. **Address Book**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default\n4. **Contact**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default/\u003cvar class=\"apiparam\" translate=\"no\"\u003econtactId\u003c/var\u003e\n\nSynchronizing Contacts\n----------------------\n\nThe following is a general description of the operations supported. Developers\nshould look for the details in the relevant RFC. Requests and responses are\nmostly encoded in XML. These are the main operations used by client\napplications for synchronization:\n\n- **Using CTag**\n - Client programs use the `getctag` `PROPFIND` request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a `sync-token` is invalidated. Periodically polling for the `getctag` property will result in throttling.\n- **Using sync-token**\n - Client programs use the `sync-token` `PROPFIND` request on the Address Book to obtain the `sync-token` representing its current state. Client applications must store this value and issue periodic `sync-collection` `REPORT` requests to determine changes since the last issued `sync-token`. Issued tokens are valid for 29 days, and the `REPORT` response will contain a new `sync-token`.\n- **Using ETags**\n - Client applications issue a `getetag` `PROPFIND` request on the Address Book resource (with `DEPTH` header equal to `DEPTH_1`). By maintaining the `ETag` value of each contact, a client program can request the value of contacts that had their `ETag` changed.\n- **Retrieving contacts**\n - Client applications retrieve contacts by issuing an `addressbook-multiget` `REPORT` request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an `ETag` for the contact.\n- **Inserting a contact**\n - Client applications issue a `POST` request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.\n- **Updating a contact**\n - Client applications issue a `PUT` request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.\n - Client applications should include an `If-Match` header with the contact's currently known `ETag`. The server will then reject the `PUT` request (with `HTTP 412`) if the current `ETag` on the server is different from the `ETag` sent by the client program. This allows for optimistic serialization of updates.\n- **Deleting a contact**\n - Client applications delete a contact by issuing a `DELETE` request against the contact URI."]]
