Esta página foi traduzida pela API Cloud Translation.

Gerenciar contatos com o protocolo CardDAV

Você pode ver 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 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 funcionar corretamente.

Para cada especificação relevante, o suporte a CardDAV do Google é o seguinte:

rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)
- Oferece suporte aos métodos HTTP GET, PUT, DELETE, OPTIONS e PROPFIND.
- Não é compatível com os métodos HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL.
- Não é compatível com propriedades arbitrárias (definidas pelo usuário) do WebDAV.
- Não oferece suporte ao controle de acesso WebDAV (rfc3744).
rfc5995: como usar POST para adicionar participantes a coleções WebDAV
- Permite criar novos contatos sem especificar um código.
rfc6352: CardDAV: extensões do vCard para criação e controle de versões distribuídos da Web (WebDAV)
- Oferece suporte ao método HTTP REPORT, mas nem todos os relatórios definidos são implementados.
- Permite fornecer uma coleção de contatos principais e uma de contatos.
rfc6578: sincronização da coleção para WebDAV
- Os aplicativos clientes precisam alternar para esse modo de operação após a sincronização inicial.
rfc6749: o OAuth 2.0 Authorization Framework e rfc6750: o OAuth 2.0 Authorization Framework: uso do token do portador
- Compatibilidade com a autenticação de programas de cliente CardDAV usando a autenticação HTTP OAuth 2.0. O Google não oferece suporte a nenhum outro método de autenticação. Para segurança dos dados de contato, exigimos que as conexões CardDAV usem HTTPS.
rfc6764: Location Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
- A inicialização de URLs do CardDAV precisa ocorrer de acordo com a seção 6 da RFC6764.
Oferece suporte à caldav-ctag-02: tag de entidade de coleta de agendas (CTag) no CalDAV, que é compartilhada entre as especificações CardDAV e CalDAV. O ctag dos contatos é 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 é necessário sincronizar nenhum contato alterado.
O Google usa o VCard 3.0 como formato de codificação de contato. Consulte: rfc6350: VCard 3.0.

O CardDAV do Google requer OAuth 2.0.

A interface CardDAV do Google requer OAuth 2.0. Consulte a documentação vinculada abaixo para ver 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 URI do catálogo de endereços e dos recursos de contato. Não codifique 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 ela chegue por HTTPS com a autenticação OAuth 2.0 de uma Conta do Google, e o aplicativo esteja registrado no DevConsole. Qualquer tentativa de conexão por HTTP com 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 primeiro precisa se conectar 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 de 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. A descrição completa desse processo está além do escopo deste documento. Consulte rfc6352 (link em inglês) 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 (de acordo com a rfc6764, link em inglês). Os dispositivos precisam repetir a descoberta de URI conhecida periodicamente para verificar se o caminho em cache ainda está atualizado e sincronizar novamente se o caminho mudar. O Google recomenda uma taxa de duas a quatro semanas.

Recursos

O CardDAV usa conceitos REST. Os aplicativos clientes atuam em recursos designados pelos URIs. A estrutura atual do URI é especificada aqui para ajudar os desenvolvedores a entender os conceitos na seção a seguir. 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
Casa
- 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

Veja a seguir uma descrição geral das operações aceitas. Os desenvolvedores precisam procurar os detalhes no RFC relevante. Geralmente, as solicitações e respostas são 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 getctag PROPFIND no recurso de catálogo de endereços para determinar se algum contato mudou no servidor e, portanto, se uma sincronização é necessária. O valor dessa propriedade será alterado se qualquer contato for alterado. Os aplicativos clientes precisam armazenar esse valor e usá-lo apenas na sincronização inicial e como um substituto quando um sync-token for invalidado. A pesquisa periódica da propriedade getctag resultará na limitação.
Como usar o token de sincronização
- Os programas clientes usam a solicitação sync-token PROPFIND no catálogo de endereços para receber o sync-token que representa o estado atual dele. Os aplicativos clientes precisam armazenar esse valor e emitir solicitações sync-collection REPORT periódicas para determinar as alterações desde a última emissão sync-token. Os tokens emitidos são válidos por 29 dias, e a resposta REPORT conterá um novo sync-token.
Como usar ETags
- Os aplicativos cliente emitem uma solicitação getetag PROPFIND 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.
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.
Inserir um contato
- Os aplicativos clientes emitem uma solicitação POST com o novo contato no formato VCard 3.0. A resposta conterá o ID do novo contato.
Atualizar um contato
- Os aplicativos cliente emitem uma solicitação PUT com o contato atualizado no formato VCard 3.0. O contato será atualizado se ele já existir no catálogo de endereços.
- Os aplicativos clientes precisam incluir um cabeçalho If-Match com o ETag conhecido do contato no momento. O servidor rejeitará a solicitação PUT (com HTTP 412) se a ETag atual no servidor for diferente da ETag enviada pelo programa cliente. Isso permite a serialização otimista das atualizações.
Excluir um contato
- Os aplicativos clientes excluem um contato emitindo uma solicitação DELETE no URI de contato.