Guide du développeur de l'API CalDAV

CalDAV est une extension de WebDAV qui permet aux clients d'accéder aux informations d'agenda sur un serveur distant.

Google fournit une interface CalDAV que vous pouvez utiliser pour afficher et gérer des agendas à l'aide du protocole CalDAV.

Spécifications

Pour chacune des spécifications pertinentes, la prise en charge de CalDAV par Google est la suivante:

  • rfc4918: Extensions HTTP pour l'édition et la gestion des versions distribuées sur le Web (WebDAV)
    • Compatible avec les méthodes HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND et PROPPATCH.
    • N'est pas compatible avec les méthodes HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL, ni avec l'en-tête If* (sauf pour If-Match).
    • Ne prend pas en charge les propriétés WebDAV arbitraires (définies par l'utilisateur).
    • Non compatible avec le contrôle des accès WebDAV (rfc3744).
  • rfc4791: Extensions de calendrier pour WebDAV (CalDAV)
    • Compatible avec la méthode HTTP REPORT. Tous les rapports, à l'exception de "free-busy-query", sont implémentés.
    • La méthode HTTP MKCALENDAR n'est pas prise en charge.
    • L'action AUDIO n'est pas prise en charge.
  • rfc5545: iCalendar
    • Les données exposées dans l'interface CalDAV sont mises en forme conformément aux spécifications iCalendar.
    • Les données VTODO ou VJOURNAL ne sont pas compatibles pour le moment.
    • Elle n'est pas compatible avec l'extension Apple iCal® pour autoriser les propriétés d'URL pouvant être définies par l'utilisateur.
  • rfc6578: Collection Synchronization for WebDAV
    • Les applications clientes doivent passer à ce mode de fonctionnement après la synchronisation initiale.
  • rfc6638: Extensions de planification pour CalDAV
    • Compatible avec une "boîte de réception" simple, qui est toujours vide.
    • Les invitations que vous recevez sont automatiquement envoyées dans votre collection "Événements" plutôt que dans votre "Boîte de réception".
    • Ne prend pas en charge la recherche de disponibilité.
  • caldav-ctag-02: balise d'entité de collection d'agenda (CTag) dans CalDAV
    • L'ctag de l'agenda est comme une etag de ressource. Il change lorsque quelque chose dans l'agenda a changé. Cela permet à l'application cliente de déterminer rapidement qu'elle n'a pas besoin de synchroniser les événements modifiés.
  • calendar-proxy: fonctionnalité de proxy utilisateur Agenda dans CalDAV
    • Pour améliorer les performances de la synchronisation du calendrier à partir d'appareils iOS, qui ne prennent pas en charge la délégation, l'utilisation des propriétés calendar-proxy-read-for ou calendar-proxy-write-for avec un UserAgent iOS échouera.

Nous n'avons pas encore implémenté l'intégralité des spécifications pertinentes. Toutefois, pour de nombreux clients tels que l'application Agenda d'Apple, le protocole CalDAV devrait interagir correctement.

Remarque: Pour la sécurité du compte et pour éviter tout abus, Google peut définir des cookies sur les applications clientes qui accèdent aux données via CalDAV.

Créer votre ID client

Pour utiliser l'API CalDAV, vous devez disposer d'un compte Google. Si vous avez déjà un compte que vous pouvez utiliser, vous n'avez rien à faire.

Avant de pouvoir envoyer des requêtes à l'API CalDAV, vous devez enregistrer votre client auprès de la console d'API Google en créant un projet.

Accédez à la console Google APIs. Cliquez sur Créer un projet, saisissez un nom, puis cliquez sur Créer.

L'étape suivante consiste à activer l'API CalDAV.

Pour activer une API pour votre projet, procédez comme suit :

  1. Dans la console Google APIs, ouvrez la bibliothèque des API. Si vous y êtes invité, sélectionnez un projet ou créez-en un. La bibliothèque des API répertorie toutes les API disponibles, regroupées par famille de produits et classées en fonction de leur popularité.
  2. Si l'API que vous souhaitez activer n'apparaît pas dans la liste, utilisez la fonctionnalité de recherche pour la trouver.
  3. Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
  4. Si vous y êtes invité, activez la facturation.
  5. Si vous y êtes invité, acceptez les conditions d'utilisation de l'API.
Pour effectuer des requêtes à l'API CalDAV, vous avez besoin d'un ID client et d'un secret client.

Pour trouver l'ID client et le code secret du client pour votre projet, procédez comme suit:

  1. Sélectionnez des identifiants OAuth 2.0 existants ou ouvrez la page Identifiants.
  2. Si vous ne l'avez pas déjà fait, créez les identifiants OAuth 2.0 de votre projet en cliquant sur Créer des identifiants > ID client OAuth, puis en fournissant les informations nécessaires pour les créer.
  3. Recherchez l'ID client dans la section ID client OAuth 2.0. Pour en savoir plus, cliquez sur l'ID client.

Se connecter au serveur CalDAV de Google

Pour utiliser l'interface CalDAV, un programme client se connecte initialement au serveur de calendrier à l'un des deux points de départ. Dans les deux cas, la connexion doit être établie via HTTPS et utiliser le schéma d'authentification OAuth 2.0. Le serveur CalDAV refuse d'authentifier une requête, sauf si elle arrive via HTTPS avec l'authentification OAuth 2.0 d'un compte Google. Une tentative de connexion via HTTP ou à l'aide de l'authentification de base génère un code d'état HTTP 401 Unauthorized.

Si le programme client (comme l'application Agenda d'Apple) nécessite une collection principale comme point de départ, l'URI à laquelle se connecter est la suivante:

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

Où calid doit être remplacé par l'ID de l'agenda auquel vous souhaitez accéder. Pour y accéder via l'interface Web de Google Agenda, procédez comme suit: dans le menu déroulant à côté du nom de l'agenda, sélectionnez Paramètres de l'agenda. Sur la page qui s'affiche, l'ID de l'agenda s'affiche dans une section intitulée Adresse de l'agenda. L'ID de l'agenda principal d'un utilisateur est identique à son adresse e-mail.

Si un programme client (tel que Mozilla Sunbird) nécessite une collection de calendriers comme point de départ, l'URI à laquelle se connecter est la suivante:

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

L'ancien point de terminaison https://www.google.com/calendar/dav est obsolète et n'est plus pris en charge. Utilisez-le à vos risques et périls. Nous vous recommandons de passer au nouveau format de point de terminaison décrit ci-dessus.

iCal® est une marque d'Apple Inc.