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. Seu aplicativo cliente pode usar a API CardDAV para criar novos contatos, editar ou excluir contatos existentes e consultar contatos que atendem a critérios específicos.
Especificações
A especificação completa não foi implementada, mas muitos clientes, como Contatos do Apple iOSTM e o macOS devem operar 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
ePROPFIND
. - Não oferece suporte aos métodos HTTP
LOCK
,UNLOCK
,COPY
,MOVE
ouMKCOL
. - Não oferece suporte a propriedades WebDAV arbitrárias (definidas pelo usuário).
- Não compatível com o controle de acesso WebDAV (rfc3744).
- Dá suporte aos métodos HTTP
- rfc5995: POST para adicionar membros a coleções WebDAV
- Oferece suporte à 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 implementado. - Dá 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 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: Localização de serviços de extensões de agenda para WebDAV (CalDAV) e extensões de vCard para WebDAV (CardDAV)
- O bootstrapping dos URLs do CardDAV deve ocorrer de acordo com a seção 6 do rfc6764.
- Oferece suporte
caldav-ctag-02: Tag de entidade da coleção da agenda (CTag) no CalDAV,
que é compartilhado entre as especificações CardDAV e CalDAV. Contatos
ctag
é como um recursoETag
; muda quando algo no contato lista de endereços mudou. 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 OAuth 2.0. Consulte os links documentação abaixo para obter informações sobre como usar o OAuth 2.0 para acessar as APIs do Google:
- Como usar o OAuth 2.0 para acessar as APIs do Google
- Como usar o OAuth 2.0 para aplicativos instalados
Como se conectar ao servidor CardDAV do Google
O protocolo CardDAV permite a descoberta do catálogo de endereços e dos recursos de contato URIs. Não fixe os URIs no código, porque eles podem mudar a qualquer momento.
Os aplicativos clientes precisam usar HTTPS, e a autenticação OAuth 2.0
precisa ser
fornecido 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, seu programa cliente precisa se conectar inicialmente à
caminho de descoberta 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. Seu programa cliente pode descobrir o catálogo de endereços principal
executando um PROPFIND
no addressbook-home-set
e procurando
addressbook
e collection
. Uma descrição completa deste processo
estão 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 desenvolvedores a entender os conceitos da seção a seguir. A estrutura pode pode ser alterado e não pode ser fixado no código. Em vez disso, é preciso descobrir os recursos de acordo com o RFC.
- Principal
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Setor para casa
- 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
Veja a seguir uma descrição geral das operações compatíveis. Desenvolvedores deve procurar os detalhes no RFC relevante. Solicitações e respostas são principalmente codificadas em XML. Estas são as principais operações usadas pelo cliente para sincronização:
- Como usar a CTag
- Os programas clientes usam a solicitação
getctag
PROPFIND
no catálogo de endereços para determinar se algum contato foi alterado no servidor e portanto, se uma sincronização é necessária. O valor desta propriedade tem a garantia de mudar caso algum contato mude. Aplicativos clientes deve armazenar esse valor e usá-lo somente na sincronização inicial e como substituto quando umsync-token
for invalidado. Pesquisando periodicamentegetctag
vai resultar na limitação.
- Os programas clientes usam a solicitação
- Como usar o sync-token
- Os programas clientes usam a solicitação
sync-token
PROPFIND
no endereço Reserve para receber osync-token
que representa o estado atual dele. Cliente aplicativos devem armazenar este valor e emitirsync-collection
periódicosREPORT
solicitações para determinar as mudanças desde a última emissãosync-token
Os tokens emitidos são válidos por 29 dias, e oREPORT
a resposta vai conter um novosync-token
.
- Os programas clientes usam a solicitação
- Como usar ETags
- Aplicativos clientes emitem uma solicitação
getetag
PROPFIND
no endereço Reservar recurso (com cabeçalhoDEPTH
igual aDEPTH_1
). Ao manter o valorETag
de cada contato, um programa cliente poderá solicitar o valor dos contatos que tiveram oETag
alterado.
- Aplicativos clientes emitem uma solicitação
- Como recuperar contatos
- Os aplicativos clientes recuperam contatos emitindo uma
addressbook-multiget
solicitação deREPORT
. Dada uma lista de URIs de contato, o relatório retorna todos os contatos solicitados como valores de VCard 3.0. Cada a entrada inclui umETag
para o contato.
- Os aplicativos clientes recuperam contatos emitindo uma
- Inserir um contato
- Os aplicativos clientes emitem uma solicitação
POST
com o novo contato no VCard. 3.0. A resposta conterá o ID do novo contato.
- Os aplicativos clientes emitem uma solicitação
- Como atualizar um contato
- Os aplicativos clientes emitem uma solicitação
PUT
com o contato atualizado em 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 oETag
conhecido do contato. O servidor rejeitará a solicitaçãoPUT
solicitação (comHTTP 412
) se oETag
atual no servidor for diferente doETag
enviado pelo programa cliente. Isso permite serialização otimista de atualizações.
- Os aplicativos clientes emitem uma solicitação
- Como excluir um contato
- Aplicativos clientes excluem um contato emitindo uma solicitação
DELETE
ao URI do contato.
- Aplicativos clientes excluem um contato emitindo uma solicitação