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.

L'API CalDAV est soumise aux mêmes limites de quota que l'API Calendar. Pour en savoir plus, consultez Limites d'utilisation.

Spécifications

Pour chacune des spécifications pertinentes, la compatibilité de Google avec CalDAV est la suivante :

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

    • Compatible avec les méthodes HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND et PROPPATCH.
    • Non compatible avec les méthodes HTTP LOCK, UNLOCK, COPY, MOVE, MKCOL ni avec l'en-tête If* (à l'exception de If-Match).
    • Non compatible avec les propriétés WebDAV arbitraires (définies par l'utilisateur).
    • Non compatible avec le contrôle d'accès WebDAV (rfc3744).

  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)

    • Compatible avec la méthode HTTP REPORT. Tous les rapports, à l'exception de free-busy-query, sont implémentés.
    • 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 mises en forme conformément à la spécification iCalendar.
    • Non compatible avec les données VTODO ni VJOURNAL.
    • Non compatible avec l'extension Apple iCal permettant de définir des propriétés d'URL par l'utilisateur.

  • rfc6578: Collection Synchronization for WebDAV

    • Les applications clientes doivent passer à ce mode de fonctionnement après la synchronisation initiale.

  • rfc6638: Scheduling Extensions to CalDAV

    • Compatible avec une "boîte de réception" triviale, 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".
    • Non compatible avec la recherche free-busy.

  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

    • Le ctag de l'agenda est semblable à un etag de ressource. Il change lorsque quelque chose est modifié dans l'agenda. Cela permet à l'application cliente de déterminer rapidement qu'elle n'a pas besoin de synchroniser les événements modifiés.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • Pour améliorer les performances de synchronisation de l'agenda, les requêtes qui incluent les propriétés calendar-proxy-read-for ou calendar-proxy-write-for échoueront avec un UserAgent iOS, car les appareils iOS ne sont pas compatibles avec la délégation.

Bien que notre implémentation CalDAV ne couvre pas toutes les spécifications, elle fonctionne correctement pour de nombreux clients, y compris Apple Agenda.

Créer votre ID client

Pour utiliser l'API CalDAV, vous devez disposer d'un compte Google Account.

Avant de pouvoir envoyer des requêtes à l'API CalDAV, vous devez enregistrer votre client auprès de la console Google Cloud 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.

Vous devez ensuite 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 d'API CalDAV , vous avez besoin d'un ID client et d'un 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 à la création des identifiants.
  3. Recherchez l'ID client dans la section ID clients 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 d'agenda à l'un des deux points de départ. Dans les deux cas, la connexion doit être établie 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 d'utilisation de l'authentification de base génère un code d'état HTTP 401 Unauthorized.

Si le programme client (tel que 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/CALENDAR_ID/user

Remplacez CALENDAR_ID par l'ID de l'agenda auquel accéder.

Pour trouver l'ID de l'agenda via l'interface Web, sélectionnez **Paramètres de l'agenda** dans le menu déroulant à côté du nom de l'agenda. L'ID de l'agenda s'affiche dans une section intitulée Adresse URL 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 Thunderbird) nécessite une collection d'agendas comme point de départ, utilisez l'URI suivante :

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