É possível 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. Seu aplicativo cliente pode usar a API CardDAV para criar novos contatos, editar ou excluir contatos existentes e consultar contatos que correspondam a critérios específicos.
Especificações
A especificação completa não foi implementada, mas muitos clientes, como Apple iOSTM Contacts e macOS, precisam interoperar corretamente.
Para cada especificação relevante, o suporte a CardDAV do Google é o seguinte:
- rfc2518: extensões HTTP para criação distribuída (WebDAV)
- Oferece suporte aos métodos HTTP
GET
,PUT
,DELETE
,OPTIONS
ePROPFIND
. - Não oferece suporte aos métodos HTTP
LOCK
,UNLOCK
,COPY
,MOVE
ouMKCOL
. - Não é compatível com propriedades WebDAV arbitrárias (definidas pelo usuário).
- Não oferece suporte ao controle de acesso WebDAV (rfc3744).
- Oferece suporte aos métodos HTTP
- rfc5995: como usar POST para adicionar membros a coleções do WebDAV
- Oferece suporte à criação de novos contatos sem especificar um ID.
- rfc6352: CardDAV: Extensions Extensions para criação e controle de versões distribuídos na Web (WebDAV)
- Oferece suporte ao método HTTP
REPORT
, mas nem todos os relatórios definidos foram implementados. - Oferece suporte ao fornecimento de uma coleção principal e uma coleção de contatos.
- Oferece suporte ao método HTTP
- rfc6578: sincronização de coleções para WebDAV
- Os aplicativos clientes precisam alternar para esse modo de operação após a sincronização inicial.
- rfc6749: framework de autorização OAuth 2.0 e
rfc6750: framework de autorização OAuth 2.0: uso do token do portador
- É compatível com a autenticação de programas de clientes CardDAV usando a autenticação HTTP do OAuth 2.0. O Google não oferece suporte a nenhum outro método de autenticação. Para a segurança dos dados de contato, exigimos que as conexões CardDAV usem HTTPS.
- rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
- O bootstrap de URLs CardDAV precisa ocorrer de acordo com a seção 6 de rfc6764.
- Compatível com caldav-ctag-02: Calendar Collection Entity Tag (CTag) no CalDAV,
que é compartilhada entre as especificações CardDAV e CalDAV. Os contatos
ctag
são como um recursoETag
: ele muda quando algo no catálogo de endereços de contatos muda. Isso permite que o programa cliente determine rapidamente que não precisa sincronizar nenhum contato modificado. - 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 informações sobre 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 do catálogo de endereços e dos URIs de recursos de contato. Não fixe no código nenhum URI, porque ele pode 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 chegue por HTTPS com autenticação OAuth 2.0
de uma Conta do Google, e seu aplicativo esteja registrado no
DevConsole. Qualquer tentativa de se conectar por HTTP com a autenticação básica ou com
um e-mail/senha que não corresponda a uma Conta do Google resulta em um código de resposta
HTTP 401 Unauthorized
.
Para usar o CardDAV, seu programa cliente precisa se conectar inicialmente ao caminho de descoberta
canônico executando um PROPFIND
HTTP em:
https://www.googleapis.com/.well-known/carddav
Depois de redirecionado (HTTP 301
) para um recurso de catálogo de endereços, o programa cliente pode executar um PROPFIND
nele para descobrir as propriedades DAV:current-user-principal
, DAV:principal-URL
e addressbook-home-set
. Seu programa cliente pode descobrir o catálogo de endereços principal
executando um PROPFIND
na addressbook-home-set
e procurando os
recursos addressbook
e collection
. Uma descrição completa desse processo
está além do escopo deste documento. Consulte rfc6352 para ver mais detalhes.
O caminho de redirecionamento retornado na resposta HTTP 301
por meio de um PROPFIND
no
URI conhecido não pode ser armazenado em cache permanentemente (como
rfc6764). Os dispositivos precisam repetir a descoberta de
URIs conhecidos periodicamente para verificar se o caminho em cache ainda está atualizado e
sincronizar novamente se o caminho mudar. O Google recomenda uma tarifa de duas a quatro semanas.
Recursos
O CardDAV usa conceitos REST. Os aplicativos clientes atuam nos recursos designados pelos URIs. A estrutura de URI atual é especificada aqui para ajudar os desenvolvedores a entender os conceitos da próxima seção. A estrutura pode mudar e não pode ser fixada no código. Em vez disso, os recursos precisam ser descobertos de acordo com o RFC.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Google Home Set
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Catálogo de endereços
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Contato
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
Como sincronizar contatos
Confira a seguir uma descrição geral das operações com suporte. Os desenvolvedores devem procurar os detalhes no RFC relevante. Geralmente, solicitações e respostas são codificadas em XML. Estas são as principais operações usadas por aplicativos clientes para sincronização:
- Como usar a CTag
- Os programas clientes usam a solicitação
PROPFIND
getctag
no recurso de catálogo de endereços para determinar se algum contato foi alterado no servidor e, portanto, se uma sincronização é necessária. O valor dessa propriedade certamente mudará se qualquer contato mudar. Os aplicativos clientes precisam armazenar esse valor e usá-lo apenas na sincronização inicial e como substituto quando umsync-token
é invalidado. Pesquisar periodicamente a propriedadegetctag
resultará na limitação.
- Os programas clientes usam a solicitação
- Como usar o token de sincronização
- Os programas clientes usam a solicitação
PROPFIND
sync-token
no catálogo de endereços para receber osync-token
que representa o estado atual. Os aplicativos clientes precisam armazenar esse valor e emitir solicitaçõessync-collection
REPORT
periódicas para determinar as mudanças desde a últimasync-token
emitida. Os tokens emitidos são válidos por 29 dias, e a respostaREPORT
terá um novosync-token
.
- Os programas clientes usam a solicitação
- Como usar ETags
- Os aplicativos clientes emitem uma solicitação
PROPFIND
getetag
no recurso de catálogo de endereços (com o cabeçalhoDEPTH
igual aDEPTH_1
). Ao manter o valorETag
de cada contato, um programa cliente pode solicitar o valor dos contatos que tiveram oETag
alterado.
- Os aplicativos clientes emitem uma solicitação
- Como recuperar contatos
- Os aplicativos clientes recuperam contatos emitindo uma
solicitação
addressbook-multiget
REPORT
. Com uma lista de URIs de contatos, o relatório retorna todos os contatos solicitados como valores do VCard 3.0. Cada entrada inclui umETag
para o contato.
- Os aplicativos clientes recuperam contatos emitindo uma
solicitação
- Como inserir um contato
- Os aplicativos clientes emitem uma solicitação
POST
com o novo contato no formato VCard 3.0. A resposta vai conter o ID do novo contato.
- Os aplicativos clientes emitem uma solicitação
- Atualizar um contato
- Os aplicativos clientes emitem uma solicitação
PUT
com o contato atualizado no formato VCard 3.0. O contato é atualizado se já existir no catálogo de endereços. - Os aplicativos clientes precisam incluir um cabeçalho
If-Match
com oETag
conhecido do contato. O servidor rejeitará a solicitaçãoPUT
(comHTTP 412
) se oETag
atual no servidor for diferente doETag
enviado pelo programa do cliente. Isso permite a serialização otimista de atualizações.
- Os aplicativos clientes emitem uma solicitação
- Como excluir um contato
- Os aplicativos clientes excluem um contato emitindo uma solicitação
DELETE
no URI do contato.
- Os aplicativos clientes excluem um contato emitindo uma solicitação