Gerenciar contatos com o protocolo CardDAV

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 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 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.

1. Principal
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Conjunto de início
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. Catálogo de endereços
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. Contato
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Sincronizar contatos

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.