Gerenciar contatos com o protocolo CardDAV
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Você pode visualizar e gerenciar seus contatos usando o protocolo CardDAV do Google.
Os contatos são armazenados na Conta do Google do usuário. a maioria dos Serviços do Google tem
acesso à lista de contatos. O aplicativo cliente pode usar a API CardDAV para
criar novos contatos, editar ou excluir contatos existentes e consultar contatos
que correspondem a critérios específicos.
Especificações
A especificação completa não foi implementada, mas muitos clientes, como
Apple iOS™ Contacts
e macOS, devem interagir corretamente.
Para cada especificação relevante, o suporte a CardDAV do Google é o seguinte:
- rfc2518: extensões HTTP para criação distribuída (WebDAV, na sigla em inglês)
- Dá suporte aos métodos HTTP
GET, PUT, DELETE, OPTIONS e
PROPFIND.
- Não oferece suporte aos métodos HTTP
LOCK, UNLOCK, COPY, MOVE ou
MKCOL.
- Não tem suporte a propriedades arbitrárias (definidas pelo usuário) do WebDAV.
- Não compatível com o controle de acesso WebDAV (rfc3744).
- rfc5995: como usar POST para adicionar membros a coleções do WebDAV
- Suporta a criação de novos contatos sem especificar um ID.
- rfc6352: CardDAV: extensões de vCard para criação distribuída pela Web e
Controle de versões (WebDAV)
- Oferece suporte ao método HTTP
REPORT, mas nem todos os relatórios definidos são
implementados.
- Dá suporte ao fornecimento de uma coleção principal e uma coleção de contatos.
- rfc6578: sincronização de coleções para WebDAV
- Os aplicativos clientes devem alternar para esse modo de operação após a
para a sincronização inicial.
- rfc6749: o framework de autorização do OAuth 2.0 e
rfc6750: o framework de autorização do OAuth 2.0: uso do token do portador
- Oferece suporte à autenticação de programas de cliente CardDAV usando OAuth 2.0 HTTP
Autenticação. O Google não oferece suporte a nenhum outro método de autenticação.
Para a segurança dos dados de contato, exigimos o uso de conexões CardDAV
HTTPS.
- rfc6764: Serviços de localização para extensões de agendamento para WebDAV (CalDAV) e extensões de vCard para WebDAV (CardDAV)
- O bootstrapping de URLs do CardDAV precisa ocorrer de acordo com a seção 6 do
rfc6764.
- Compatível
caldav-ctag-02: Tag de entidade da coleção da agenda (CTag) no CalDAV,
que é compartilhado entre as especificações CardDAV e CalDAV. O
ctag
de contatos é como um recurso ETag. Ele muda quando algo na lista de
endereços de contato muda. Isso permite que o programa cliente determine rapidamente
que não seja necessário sincronizar nenhum contato alterado.
- O Google usa o VCard 3.0 como formato de codificação de contatos. Consulte:
rfc6350: VCard 3.0.
O CardDAV do Google exige o OAuth 2.0
A interface CardDAV do Google exige o OAuth 2.0. Consulte a documentação
vinculada abaixo para saber como usar o OAuth 2.0 para acessar as APIs do Google:
Como se conectar ao servidor CardDAV do Google
O protocolo CardDAV permite a descoberta dos URIs de recursos de catálogo de endereços e de contato. Não é necessário codificar nenhum URI, porque eles podem mudar a qualquer momento.
Os aplicativos clientes precisam usar HTTPS, e a autenticação OAuth 2.0 precisa ser
fornecida para a Conta do Google do usuário. O servidor CardDAV não
autenticar uma solicitação, a menos que ela chegue por HTTPS com o OAuth 2.0
autenticação de uma conta do Google e seu aplicativo estiver registrado no
DevConsole: Qualquer tentativa de conexão por HTTP com a autenticação básica ou
um e-mail/senha que não corresponde a uma Conta do Google resulta em uma solicitação
Código de resposta 401 Unauthorized.
Para usar o CardDAV, o programa cliente precisa se conectar inicialmente ao caminho de descoberta
canônico executando um PROPFIND HTTP em:
https://www.googleapis.com/.well-known/carddav
Após ser redirecionado (HTTP 301) para um recurso do Catálogo de endereços, seu programa cliente
pode executar um PROPFIND nele para descobrir os
DAV:current-user-principal, DAV:principal-URL e addressbook-home-set
propriedades. O programa do cliente pode descobrir a agenda de endereços principal
realizando uma PROPFIND no addressbook-home-set e procurando os
recursos addressbook e collection. Uma descrição completa desse processo
está fora do escopo deste documento. Consulte
rfc6352 para mais detalhes.
O caminho de redirecionamento retornado na resposta HTTP 301 usando um PROPFIND em
o URI conhecido não pode ser armazenado em cache permanentemente (conforme
rfc6764). Os dispositivos devem tentar novamente com nomes conhecidos
descoberta de URI periodicamente para verificar se o caminho em cache ainda está atualizado e
e ressincronizar se o caminho for alterado. O Google recomenda uma taxa de duas a quatro semanas.
Recursos
O CardDAV usa os conceitos do REST. Os aplicativos clientes agem em recursos
são designados pelos URIs deles. A estrutura de URI atual é especificada aqui para ajudar
os desenvolvedores a entender os conceitos na próxima seção. A estrutura pode
mudar e não pode ser codificada. Em vez disso, é preciso descobrir os recursos
de acordo com o RFC.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Conjunto de início
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- Catálogo de endereços
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- Contato
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
Veja a seguir uma descrição geral das operações compatíveis. Os desenvolvedores
precisam procurar os detalhes no RFC relevante. Solicitações e respostas são
principalmente codificadas em XML. Estas são as principais operações usadas pelos aplicativos
clientes para sincronização:
- Como usar a CTag
- Os programas clientes usam a solicitação
PROPFIND getctag no recurso da agenda
para determinar se algum contato foi alterado no servidor e,
portanto, se uma sincronização é necessária. O valor dessa propriedade
vai mudar se qualquer contato mudar. Os aplicativos clientes
precisam armazenar esse valor e usá-lo apenas na sincronização inicial e como uma
alternativa quando um sync-token for invalidado. A pesquisa periódica da propriedade
getctag resultará em limitação.
- Como usar o sync-token
- Os programas clientes usam a solicitação
PROPFIND sync-token no catálogo de endereços
para receber o sync-token que representa o estado atual. Os aplicativos
clientes precisam armazenar esse valor e emitir solicitações periódicas de sync-collection
REPORT para determinar as mudanças desde a última
sync-token emitida. Os tokens emitidos são válidos por 29 dias, e o REPORT
a resposta vai conter um novo sync-token.
- Como usar ETags
- Os aplicativos clientes emitem uma solicitação
PROPFIND getetag no recurso
do catálogo de endereços (com cabeçalho DEPTH igual a DEPTH_1). Ao manter
o valor ETag de cada contato, um programa cliente pode solicitar o valor
dos contatos que tiveram o ETag alterado.
- Recuperando contatos
- Os aplicativos clientes recuperam contatos emitindo uma
solicitação
REPORT addressbook-multiget. Dada uma lista de URIs de contato,
o relatório retorna todos os contatos solicitados como valores do VCard 3.0. Cada
entrada inclui um ETag para o contato.
- Como inserir um contato
- Os aplicativos clientes emitem uma solicitação
POST com o novo contato no VCard.
3.0. A resposta vai conter o ID do novo contato.
- Atualização de um contato
- Os aplicativos clientes emitem uma solicitação
PUT com o contato atualizado no
formato VCard 3.0. O contato será atualizado se já existir
no catálogo de endereços.
- Os aplicativos clientes precisam incluir um cabeçalho
If-Match com o
ETag conhecido do contato. O servidor rejeitará a solicitação PUT
solicitação (com HTTP 412) se o ETag atual no servidor for
diferente do ETag enviado pelo programa cliente. Isso permite
a serialização otimista de atualizações.
- Como excluir um contato
- Aplicativos clientes excluem um contato emitindo uma solicitação
DELETE
ao URI do contato.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-07-25 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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."]]
