Guia do desenvolvedor da API CalDAV

CalDAV é uma extensão do WebDAV que fornece um padrão para os clientes acessarem informações da agenda em um servidor remoto.

O Google fornece uma interface CalDAV que pode ser usada para visualizar e gerenciar agendas com o protocolo CalDAV.

Especificações

Para cada uma das especificações relevantes, o suporte a CalDAV do Google é o seguinte:

  • rfc4918: extensões HTTP para criação e controle de versão distribuído na Web (WebDAV)
    • Oferece suporte aos métodos HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND e PROPPATCH.
    • Não é compatível com os métodos HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL ou com o cabeçalho If*, exceto If-Match.
    • Não oferece suporte a propriedades arbitrárias (definidas pelo usuário) do WebDAV.
    • Não oferece suporte ao controle de acesso WebDAV (rfc3744).
  • RFC4791: extensões de agenda para WebDAV (CalDAV)
    • Oferece suporte ao método HTTP REPORT. Todos os relatórios, exceto a consulta disponível-ocupado, são implementados.
    • Não é compatível com o método HTTP MKCALENDAR.
    • Não é compatível com a ação AUDIO.
  • rfc5545: iCalendar
    • Os dados expostos na interface CalDAV são formatados de acordo com a especificação iCalendar.
    • Não oferece suporte a dados de VTODO ou VJOURNAL no momento.
    • Não é compatível com a extensão Apple iCal® para permitir propriedades de URL definidas pelo usuário.
  • 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.
  • rfc6638: como programar extensões no CalDAV
    • Compatível com uma "caixa de entrada" comum, que está sempre vazia.
    • Os convites recebidos são entregues automaticamente na sua coleção de "eventos" em vez de serem colocados na sua "caixa de entrada".
    • Não oferece suporte para pesquisa de disponibilidade.
  • caldav-ctag-02: tag de entidade de coleta de agenda (CTag) no CalDAV
    • A agenda ctag é como um recurso etag, que muda quando algo muda na agenda. Isso permite que o aplicativo cliente determine rapidamente que não precisa sincronizar os eventos alterados.
  • calendar-proxy: funcionalidade do proxy do usuário do Google Agenda no CalDAV
    • Para melhorar o desempenho da sincronização de agendas em dispositivos iOS, que não são compatíveis com a delegação, o uso das propriedades calendar-proxy-read-for ou calendar-proxy-write-for com um UserAgent do iOS falhará.

Ainda não fornecemos uma implementação completa de todas as especificações relevantes. No entanto, para muitos clientes, como o Apple iCal, o protocolo CalDAV precisará interoperar corretamente.

Observação: para a segurança da conta e para evitar abusos, o Google pode definir cookies em aplicativos clientes que acessam dados via CalDAV.

Como criar seu ID do cliente

Para usar a API CalDAV, você precisa ter uma Conta do Google. Se você já tem uma conta para usar, não precisa fazer mais nada.

Antes de enviar solicitações para a API CalDAV, registre seu cliente no Console de APIs do Google criando um projeto.

Vá para o Console de APIs do Google. Clique em Criar projeto, insira um nome e clique em Criar.

A próxima etapa é ativar a API CalDAV.

Para ativar uma API no seu projeto, siga estas etapas:

  1. Abra a biblioteca de APIs no Console de APIs do Google. Se solicitado, selecione um projeto ou crie um novo. A biblioteca de APIs lista todas as APIs disponíveis agrupadas por família de produtos e popularidade.
  2. Se a API que você quer ativar não estiver visível na lista, use a pesquisa para encontrá-la.
  3. Selecione a API que você quer ativar e clique no botão Ativar.
  4. Se necessário, ative o faturamento.
  5. Aceite os Termos de Serviço da API, se solicitado.
Para executar as solicitações da API CalDAV, você precisará do ID do cliente e da chave secreta do cliente.

Para localizar o ID do cliente e a chave secreta do cliente do projeto, faça o seguinte:

  1. Selecione uma credencial OAuth 2.0 atual ou abra a página Credenciais.
  2. Se você ainda não tiver feito isso, crie as credenciais do OAuth 2.0 do seu projeto clicando em Criar credenciais > ID do cliente OAuth e fornecendo as informações necessárias para criá-las.
  3. Procure o ID do cliente na seção IDs do cliente do OAuth 2.0. Para saber mais detalhes, clique no ID do cliente.

Como se conectar ao servidor CalDAV do Google

Para usar a interface CalDAV, um programa cliente primeiro se conecta ao servidor da agenda em um de dois pontos de partida. Em ambos os casos, a conexão precisa ser feita por HTTPS e precisa usar o esquema de autenticação OAuth 2.0. O servidor do CalDAV recusará a autenticação de uma solicitação a menos que ela chegue por HTTPS com a autenticação OAuth 2.0 de uma Conta do Google. A tentativa de conexão por HTTP ou uso da autenticação básica resulta em um código de status HTTP 401 Unauthorized.

Se o programa cliente (como Apple iCal) exigir uma coleção principal como ponto de partida, o URI para se conectar será:

https://apidata.googleusercontent.com/caldav/v2/calid/user

Em que calid precisa ser substituído pelo "ID da agenda" que será acessado. Você pode encontrar essa opção na interface da Web do Google Agenda da seguinte forma: no menu suspenso ao lado do nome da agenda, selecione Configurações da agenda. Na página resultante, o ID da agenda é mostrado em uma seção chamada Endereço da agenda. O ID da agenda principal de um usuário é o mesmo endereço de e-mail dele.

Se um programa cliente (como o Mozilla Sunbird) exigir uma coleção de agendas como ponto de partida, o URI de conexão será:

https://apidata.googleusercontent.com/caldav/v2/calid/events

O endpoint antigo https://www.google.com/calendar/dav foi descontinuado e não recebe mais suporte. Use-o por sua conta e risco. Recomendamos que você faça a transição para o novo formato de endpoint descrito acima.

iCal é uma marca registrada da Apple Inc.