Esta página foi traduzida pela API Cloud Translation.

Gerenciar contatos com o protocolo CardDAV

É 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 e PROPFIND.
- Não oferece suporte aos métodos HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL.
- Não é compatível com propriedades WebDAV arbitrárias (definidas pelo usuário).
- Não oferece suporte ao controle de acesso WebDAV (rfc3744).
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.
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 recurso ETag: 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
Google Home Set
- 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

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 um sync-token é invalidado. Pesquisar periodicamente a propriedade getctag resultará na limitaçã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 o sync-token que representa o estado atual. Os aplicativos clientes precisam armazenar esse valor e emitir solicitações sync-collection REPORT periódicas para determinar as mudanças desde a última sync-token emitida. Os tokens emitidos são válidos por 29 dias, e a resposta REPORT terá um novo sync-token.
Como usar ETags
- Os aplicativos clientes emitem uma solicitação PROPFIND getetag no recurso de catálogo de endereços (com o 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.
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 um ETag para o contato.
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.
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 o ETag conhecido do contato. O servidor rejeitará a solicitação PUT (com HTTP 412) se o ETag atual no servidor for diferente do ETag enviado pelo programa do cliente. Isso permite a serialização otimista de atualizações.
Como excluir um contato
- Os aplicativos clientes excluem um contato emitindo uma solicitação DELETE no URI do contato.