Guia do desenvolvedor da API CalDAV

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

O Google oferece uma interface CalDAV que pode ser usada para visualizar e gerenciar agendas usando 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ões distribuídos da Web (WebDAV)
  • Oferece suporte aos métodos HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND e PROPPATCH.
  • Não aceita os métodos HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL, nem com o cabeçalho If* (exceto para If-Match).
  • Não é compatível com propriedades WebDAV arbitrárias (definidas pelo usuário).
  • Não é compatível com o controle de acesso WebDAV (rfc3744).
• rfc4791: extensões de calendário para WebDAV (CalDAV)
  • Oferece suporte ao método HTTP REPORT. Todos os relatórios, exceto consultas de disponibilidade, são implementados.
  • Não aceita o método HTTP MKCALENDAR.
  • Não oferece suporte à ação AUDIO.
• rfc5545: iCalendar
  • Os dados expostos na interface CalDAV são formatados de acordo com a especificação do iCalendar.
  • No momento, não é compatível com dados de VTODO ou VJOURNAL.
  • Não é compatível com a extensão do Apple iCal® para permitir propriedades de URL configuráveis pelo usuário.
• 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.
• rfc6638: Como agendar extensões para CalDAV
  • Oferece suporte a uma "caixa de entrada" trivial, que está sempre vazia.
  • Os convites recebidos são entregues automaticamente na coleção "eventos", em vez de colocados na "caixa de entrada".
  • Não oferece suporte à pesquisa de disponibilidade.
• caldav-ctag-02: tag de entidade de coleta de agenda (CTag) em CalDAV
  • A ctag da agenda é como um recurso etag e muda sempre que algo muda na agenda. Assim, o aplicativo cliente pode determinar rapidamente que não precisa sincronizar nenhum evento alterado.
• calendar-proxy: funcionalidade de proxy do usuário do Google Agenda no CalDAV
  • Para melhorar o desempenho da sincronização de agendas em dispositivos iOS, que não oferecem suporte à delegação, o uso das propriedades calendar-proxy-read-for ou calendar-proxy-write-for com um user agent do iOS vai 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 precisa interoperar corretamente.

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

Criar seu ID do cliente

Para usar a API CalDAV, você precisa ter uma Conta do Google. Se você já tem uma conta que pode usar, então está tudo pronto.

Antes de enviar solicitações à API CalDAV, é necessário registrar 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 habilitar e clique no botão Ativar.
4. Se necessário, ative o faturamento.
5. Aceite os Termos de Serviço da API, se for o caso.

Para executar solicitações da API CalDAV, você vai 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 do OAuth 2.0 atual ou abra a página Credenciais.
2. Se você ainda não fez isso, crie as credenciais do OAuth 2.0 do projeto clicando em Criar credenciais > ID do cliente OAuth e fornecendo as informações necessárias para criar as credenciais.
3. Procure o ID do cliente na seção IDs do cliente OAuth 2.0. Para mais detalhes, clique no ID do cliente.

Como se conectar ao servidor CalDAV do Google

Para usar a interface CalDAV, um programa cliente se conecta inicialmente com o servidor da agenda em um dos dois pontos de partida. Em ambos os casos, a conexão precisa ser feita por HTTPS e usar o esquema de autenticação OAuth 2.0. O servidor CalDAV não autenticará uma solicitação a menos que ele chegue por HTTPS com a autenticação OAuth 2.0 de uma Conta do Google. A tentativa de se conectar por HTTP ou usar a 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 a ser conectado será:

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

Em que calid precisa ser substituído pelo "código da agenda" da agenda que será acessada. Essa opção pode ser encontrada 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 é igual ao 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 para se conectar vai ser:

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

O endpoint antigo https://www.google.com/calendar/dav foi descontinuado e não é mais compatível. 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.