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

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

  1. Principal
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. Setor para casa
    • 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

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 um sync-token for invalidado. Pesquisando periodicamente getctag vai resultar na limitação.
  • Como usar o sync-token
    • Os programas clientes usam a solicitação sync-token PROPFIND no endereço Reserve para receber o sync-token que representa o estado atual dele. Cliente aplicativos devem armazenar este valor e emitir sync-collection periódicos REPORT solicitações para determinar as mudanças desde a última emissão sync-token Os tokens emitidos são válidos por 29 dias, e o REPORT a resposta vai conter um novo sync-token.
  • Como usar ETags
    • Aplicativos clientes emitem uma solicitação getetag PROPFIND no endereço Reservar recurso (com cabeçalho DEPTH igual a DEPTH_1). Ao manter o valor ETag de cada contato, um programa cliente poderá solicitar o valor dos contatos que tiveram o ETag alterado.
  • Como recuperar contatos
    • Os aplicativos clientes recuperam contatos emitindo uma addressbook-multiget solicitação de REPORT. 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 um ETag para o contato.
  • 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.
  • 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 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 serialização otimista de atualizações.
  • Como excluir um contato
    • Aplicativos clientes excluem um contato emitindo uma solicitação DELETE ao URI do contato.