Guia para desenvolvedores da API CalDAV

A API 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 visualizar e gerenciar agendas usando o protocolo CalDAV.

A API CalDAV tem os mesmos limites de cota da API Calendar. Para mais informações, consulte Limites de uso.

Especificações

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

  • rfc4918: extensões HTTP para autoria e controle de versão distribuídos 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, MKCOL, ou ao cabeçalho If* (exceto If-Match).
    • Não oferece suporte a propriedades WebDAV arbitrárias (definidas pelo usuário).
    • 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 free-busy-query, são implementados.
    • Não oferece suporte ao 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 iCalendar.
    • Não oferece suporte a dados VTODO ou VJOURNAL.
    • Não oferece suporte à 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 mudar para esse modo de operação após a sincronização inicial.

  • rfc6638: extensões de programação para CalDAV

    • Oferece suporte a uma "caixa de entrada" trivial, que está sempre vazia.
    • Os convites recebidos são entregues automaticamente à coleção "eventos" em vez de serem colocados na "caixa de entrada".
    • Não oferece suporte à pesquisa free-busy.

  • caldav-ctag-02: tag de entidade de coleção de agenda (CTag) no CalDAV

    • A ctag da agenda é como uma etag de recurso. Ela muda quando algo na agenda é alterado. Isso permite que o aplicativo cliente determine rapidamente que não precisa sincronizar eventos alterados.

  • calendar-proxy: funcionalidade de proxy de usuário de agenda no CalDAV

    • Para melhorar o desempenho da sincronização da agenda, as solicitações que incluem as propriedades calendar-proxy-read-for ou calendar-proxy-write-for vão falhar com um UserAgent do iOS porque os dispositivos iOS não oferecem suporte à delegação.

Embora nossa implementação do CalDAV não cubra todas as especificações, ela funciona corretamente para muitos clientes, incluindo o Apple Calendar.

Criar o ID do cliente

Para usar a API CalDAV, é necessário ter uma Conta do Google.

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

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

Em seguida, ative 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. 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 fazer solicitações da API CalDAV , você precisa de um ID do cliente e uma 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 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 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.

Conectar-se ao 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 recusa a autenticar 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 usando a autenticação básica resulta em um código de status HTTP 401 Unauthorized.

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

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

Substitua CALENDAR_ID pelo ID da agenda a ser acessada.

Para encontrar o ID da agenda na interface da Web, selecione ** Configurações da agenda** no menu suspenso ao lado do nome da agenda. 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 Thunderbird) exigir uma coleção de agendas como ponto de partida, use o seguinte URI:

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