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 qui vous permet d'afficher et de gérer des agendas à l'aide du protocole CalDAV.

Caractéristiques

Pour chacune des spécifications concernées, la compatibilité avec CalDAV de Google est assurée comme suit:

  • rfc4918: Extensions HTTP pour la création et la gestion des versions distribuées Web (WebDAV)
    • Accepte les méthodes HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND et PROPPATCH.
    • N'accepte pas les méthodes HTTP LOCK, UNLOCK, COPY, MOVE ou MKCOL, ni l'en-tête If* (sauf If-Match).
    • Incompatible avec les propriétés WebDAV arbitraires (définies par l'utilisateur).
    • Non compatible avec le contrôle d'accès WebDAV (rfc3744).
  • rfc4791: Extensions d'agenda pour WebDAV (CalDAV)
    • Accepte la méthode HTTP REPORT. Tous les rapports, à l'exception de la requête de disponibilité, sont implémentés.
    • Incompatible 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.
    • Incompatible avec les données VTODO ou VJOURNAL pour le moment.
    • Incompatible avec l'extension Apple iCal® permettant de définir des propriétés d'URL par l'utilisateur.
  • rfc6578: Synchronisation des collections pour WebDAV
    • Les applications clientes doivent passer à ce mode de fonctionnement après la synchronisation initiale.
  • rfc6638: Programmer des extensions pour CalDAV
    • Compatible avec une "boîte de réception" triviale, toujours vide.
    • Les invitations que vous recevez sont automatiquement placées dans votre collection "Événements" plutôt que dans votre "boîte de réception".
    • Incompatible avec la recherche de disponibilité.
  • caldav-ctag-02: balise d'entité de collection d'agendas (CTag) dans CalDAV
    • L'agenda ctag est semblable à une ressource etag : il change en cas de modification d'un élément de l'agenda. Cela permet à l'application cliente de déterminer rapidement qu'elle n'a pas besoin de synchroniser des événements modifiés.
  • calendar-proxy: fonctionnalité de proxy de l'utilisateur d'agenda dans CalDAV
    • Pour améliorer les performances de synchronisation des 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 l'implémentation complète de toutes les spécifications pertinentes. Toutefois, pour de nombreux clients tels que l'application Calendrier d'Apple, le protocole CalDAV devrait fonctionner correctement.

Remarque: Pour garantir la sécurité des comptes et éviter toute utilisation abusive, Google peut définir des cookies sur les applications clientes qui accèdent aux données via CalDAV.

Création de 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 êtes prêt.

Avant de pouvoir envoyer des requêtes à l'API CalDAV, vous devez enregistrer votre client dans la console Google APIs 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 d'API. 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 effectuer 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 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.
  3. Recherchez le Client ID (ID client) dans la section ID client OAuth 2.0. Pour plus d'informations, 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 disponibles. Dans les deux cas, la connexion doit être effectuée via HTTPS et doit 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 à l'aide de l'authentification de base génère un code d'état HTTP 401 Unauthorized.

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

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, sélectionnez Paramètres de l'agenda dans le menu déroulant à 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 Calendar Address (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 d'agendas comme point de départ, l'URI auquel se connecter est le suivant:

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. 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.