Guia para desenvolvedores da API CalDAV

O CalDAV é uma extensão do WebDAV que fornece 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 ver e gerenciar agendas usando o protocolo CalDAV.

Especificações

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

• rfc4918: extensões HTTP para criação e controle de versões distribuídas na Web (WebDAV)
  • Oferece suporte aos métodos HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND e PROPPATCH.
  • Não oferece suporte aos métodos HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL, nem ao cabeçalho If* (exceto 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 agenda para WebDAV (CalDAV)
  • Oferece suporte ao método HTTP REPORT. Todos os relatórios, exceto free-busy-query, 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.
  • No momento, não é compatível com dados de VTODO ou VJOURNAL.
  • Não é compatível com a extensão Apple iCal® para permitir propriedades de URL definíveis pelo usuário.
• rfc6578: sincronização de coleta para WebDAV
  • Os aplicativos clientes precisam mudar para esse modo de operação após a sincronização inicial.
• rfc6638: extensões de programação para CalDAV
  • Compatível com uma "caixa de entrada" trivial, que está sempre vazia.
  • Os convites recebidos são entregues automaticamente na sua coleção "Eventos" em vez de serem colocados na "Caixa de entrada".
  • Não é compatível com a pesquisa de disponibilidade.
• caldav-ctag-02: tag de entidade de coleção da Agenda (CTag) no CalDAV
  • A agenda ctag é como um recurso etag: ela muda quando algo na agenda é alterado. Isso permite que o aplicativo cliente determine rapidamente que não precisa sincronizar nenhum evento alterado.
• calendar-proxy: funcionalidade de proxy de usuário da Agenda no CalDAV
  • Para melhorar a sincronização do calendário 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 UserAgent do iOS vai falhar.

Ainda não oferecemos uma implementação completa de todas as especificações relevantes. No entanto, para muitos clientes, como o app Agenda da Apple, o protocolo CalDAV deve interoperar corretamente.

Observação: para garantir a segurança da conta e evitar abusos, o Google pode definir cookies em aplicativos cliente 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, então está tudo pronto.

Antes de enviar solicitações à 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.

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 for o caso.

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

Conexão com o servidor CalDAV do Google

Para usar a interface CalDAV, um programa cliente se conecta inicialmente ao servidor de agenda em um de 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 se recusará a autenticar uma solicitação a menos que ela chegue por HTTPS com autenticação OAuth 2.0 de uma Conta do Google. A tentativa de conexão por HTTP ou o uso da autenticação básica resulta em um código de status HTTP 401 Unauthorized.

Se o programa cliente (como o app Calendário da Apple) exigir uma coleção principal como ponto de partida, o URI para conexão será:

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

Em que calid precisa ser substituído pelo "ID da agenda" da agenda a ser acessada. Para encontrar essa opção, acesse a interface da Web do Google Agenda: 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 que o endereço de e-mail dele.

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

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

O endpoint antigo https://www.google.com/calendar/dav está obsoleto e não tem mais suporte. Use 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.