Guide du développeur de l'API CalDAV

CalDAV est une extension de WebDAV qui fournit une norme permettant 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 les agendas à l'aide du protocole CalDAV.

Caractéristiques

Pour chacune des caractéristiques pertinentes, la compatibilité de Google avec CalDAV est la suivante:

  • rfc4918: Extensions HTTP pour la création et la gestion de versions distribuées sur le Web (WebDAV)
    • Accepte les méthodes HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND et PROPPATCH.
    • Non compatible avec les méthodes HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL, ni avec l'en-tête If* (sauf If-Match).
    • Non compatible avec les propriétés WebDAV arbitraires (définies par l'utilisateur).
    • Non compatible avec WebDAV Access Control (rfc3744).
  • rfc4791: Extensions d'agenda vers WebDAV (CalDAV)
    • Accepte la méthode HTTP REPORT. Tous les rapports, à l'exception des rapports de disponibilité, sont mis en œuvre.
    • Non compatible avec la méthode HTTP MKCALENDAR.
    • Non compatible avec l'action AUDIO.
  • rfc5545: iCalendar
    • Les données exposées dans l'interface CalDAV sont formatées conformément à la spécification iCalendar.
    • Actuellement, il n'est pas compatible avec les données VTODO ou VJOURNAL.
    • Non compatible avec l'extension Apple iCal® pour autoriser les propriétés d'URL configurables par l'utilisateur.
  • rfc6578: Synchronisation de collection pour WebDAV
    • Les applications clientes doivent basculer sur ce mode de fonctionnement après la synchronisation initiale.
  • rfc6638: Programmer des extensions sur CalDAV
    • Accepte 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" au lieu d'être placées dans votre "boîte de réception".
    • Ne prend pas en charge la recherche de disponibilité.
  • caldav-ctag-02: tag de l'entité de collection de l'agenda (CTag) dans CalDAV
    • L'agenda ctag est semblable à une ressource etag. Il change lorsque tout ce qui y figure est modifié. 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é Proxy utilisateur de l'agenda dans CalDAV
    • Pour améliorer les performances de la synchronisation d'agendas à partir d'appareils iOS, qui ne sont pas compatibles avec la délégation, l'utilisation des propriétés calendar-proxy-read-for ou calendar-proxy-write-for avec un user-agent iOS échouera.

Nous n'avons pas encore fourni toutes les spécifications pertinentes. Toutefois, pour de nombreux clients tels qu'Apple iCal, le protocole CalDAV doit fonctionner correctement.

Remarque: Pour la sécurité des comptes et pour éviter les 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 possédez 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 avec 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. Ouvrez la bibliothèque d'API dans la console Google APIs. Si vous y êtes invité, sélectionnez un projet ou créez-en un. La bibliothèque d'API répertorie toutes les API disponibles, regroupées par famille de produits et par 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 exécuter des requêtes de l'API CalDAV, vous avez besoin de l'ID client et du code secret du client.

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

  1. Sélectionnez un identifiant OAuth 2.0 existant 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 créer les identifiants.
  3. Recherchez l'ID client dans la section ID clients OAuth 2.0. Pour en savoir plus, cliquez sur l'ID client.

Connexion au serveur CalDAV de Google

Pour utiliser l'interface CalDAV, un programme client se connecte initialement au serveur d'agenda à l'un des deux points de départ. Dans les deux cas, la connexion doit être effectuée 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. Toute tentative de connexion via HTTP ou via l'authentification de base génère un code d'état HTTP 401 Unauthorized.

Si le programme client (tel qu'Apple iCal) nécessite une collection principale comme point de départ, l'URI auquel 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 accéder. Pour y accéder via l'interface Web de Google Agenda, sélectionnez Paramètres de l'agenda dans le menu déroulant situé à côté du nom 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 d'agenda de l'agenda principal d'un utilisateur est identique à son adresse e-mail.

Si un programme client (tel que Mozilla Sunbird) a besoin d'une collection d'agendas pour commencer, l'URI auquel 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 compatible. Vous l'utilisez à vos propres risques. Nous vous recommandons de passer au nouveau format de point de terminaison décrit ci-dessus.

iCal est une marque d'Apple Inc.