Esta página foi traduzida pela API Cloud Translation.

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:

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 oferece suporte a propriedades WebDAV arbitrárias (definidas pelo usuário).
- Não compatível com o controle de acesso WebDAV (rfc3744).
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.
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 recurso ETag; 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 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
Setor para 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 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.