CalDAV API-Entwicklerhandbuch

CalDAV ist eine Erweiterung von WebDAV, die einen Standard für Clients bietet, um auf Kalenderinformationen auf einem Remote-Server zuzugreifen.

Google bietet eine CalDAV-Schnittstelle, mit der Sie Kalender über das CalDAV-Protokoll aufrufen und verwalten können.

Für die CalDAV API gelten dieselben Kontingentlimits wie für die Calendar API. Weitere Informationen finden Sie unter Nutzungslimits.

Spezifikationen

Die CalDAV-Unterstützung von Google für die einzelnen relevanten Spezifikationen ist wie folgt:

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

    • Unterstützt die HTTP-Methoden GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND und PROPPATCH.
    • Unterstützt nicht die HTTP-Methoden LOCK, UNLOCK, COPY, MOVE, MKCOL oder den Header If* (außer If-Match).
    • Beliebige (nutzerdefinierte) WebDAV-Eigenschaften werden nicht unterstützt.
    • Unterstützt keine WebDAV-Zugriffssteuerung (rfc3744).

  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)

    • Unterstützt die HTTP-Methode REPORT. Alle Berichte außer free-busy-query sind implementiert.
    • Die HTTP-Methode MKCALENDAR wird nicht unterstützt.
    • Die Aktion AUDIO wird nicht unterstützt.

  • rfc5545: iCalendar

    • Daten, die über die CalDAV-Schnittstelle bereitgestellt werden, sind gemäß der iCalendar-Spezifikation formatiert.
    • VTODO- oder VJOURNAL-Daten werden nicht unterstützt.
    • Die Apple iCal-Erweiterung wird nicht unterstützt, um nutzerdefinierte URL-Attribute zu ermöglichen.

  • rfc6578: Collection Synchronization for WebDAV

    • Clientanwendungen müssen nach der ersten Synchronisierung zu diesem Betriebsmodus wechseln.

  • rfc6638: Scheduling Extensions to CalDAV

    • Unterstützt einen trivialen „Posteingang“, der immer leer ist.
    • Einladungen, die Sie erhalten, werden automatisch in Ihrer Sammlung „Termine“ und nicht in Ihrem Posteingang abgelegt.
    • Unterstützt keine free-busy-Suche.

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

    • Der Kalender ctag ist wie eine Ressource etag. Er ändert sich, wenn sich etwas im Kalender ändert. So kann die Clientanwendung schnell feststellen, dass keine geänderten Ereignisse synchronisiert werden müssen.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • Um die Leistung der Kalendersynchronisierung zu verbessern, schlagen Anfragen, die die Eigenschaften calendar-proxy-read-for oder calendar-proxy-write-for enthalten, mit einem iOS-User-Agent fehl, da iOS-Geräte keine Delegierung unterstützen.

Unsere CalDAV-Implementierung deckt zwar nicht alle Spezifikationen ab, funktioniert aber für viele Clients, einschließlich Apple Kalender, einwandfrei.

Client-ID erstellen

Wenn Sie die CalDAV API verwenden möchten, benötigen Sie ein Google-Konto.

Bevor Sie Anfragen an die CalDAV API senden können, müssen Sie Ihren Client in der Google Cloud Console registrieren, indem Sie ein Projekt erstellen.

Gehen Sie zur Google API Console. Klicken Sie auf Projekt erstellen, geben Sie einen Namen ein und klicken Sie auf Erstellen.

Als Nächstes müssen Sie die CalDAV API aktivieren.

So aktivieren Sie eine API für Ihr Projekt:

  1. Öffnen Sie die API-Bibliothek in der Google API Console. Wählen Sie ein Projekt aus oder erstellen Sie ein neues, wenn Sie dazu aufgefordert werden. In der API-Bibliothek finden Sie alle verfügbaren APIs nach Produktfamilie und Beliebtheit gruppiert.
  2. Wenn die API, die Sie aktivieren möchten, nicht in der Liste angezeigt wird, können Sie die Suchfunktion verwenden.
  3. Wählen Sie die gewünschte API aus und klicken Sie dann auf die Schaltfläche Aktivieren.
  4. Aktivieren Sie die Abrechnung, wenn Sie dazu aufgefordert werden.
  5. Akzeptieren Sie die Nutzungsbedingungen der API, wenn Sie dazu aufgefordert werden.

Für CalDAV API-Anfragen benötigen Sie eine Client-ID und einen Clientschlüssel.

So findest du die Client-ID und den Clientschlüssel deines Projekts:

  1. Wählen Sie vorhandene OAuth 2.0-Anmeldedaten aus oder öffnen Sie die Seite „Anmeldedaten“.
  2. Falls noch nicht geschehen, erstellen Sie die OAuth 2.0-Anmeldedaten für Ihr Projekt, indem Sie auf Anmeldedaten erstellen > OAuth-Client-ID klicken und die erforderlichen Informationen angeben.
  3. Suchen Sie im Abschnitt OAuth 2.0-Client-IDs nach der Client-ID. Klicken Sie auf die Client-ID, um weitere Informationen zu erhalten.

Verbindung zum CalDAV-Server von Google herstellen

Um die CalDAV-Schnittstelle zu verwenden, stellt ein Clientprogramm zuerst über einen von zwei Startpunkten eine Verbindung zum Kalenderserver her. In beiden Fällen muss die Verbindung über HTTPS hergestellt werden und das OAuth 2.0-Authentifizierungsschema verwenden. Der CalDAV-Server lehnt die Authentifizierung einer Anfrage ab, wenn sie nicht über HTTPS mit OAuth 2.0-Authentifizierung eines Google-Kontos erfolgt. Wenn Sie versuchen, eine Verbindung über HTTP herzustellen oder die Basisauthentifizierung zu verwenden, wird der HTTP-Statuscode 401 Unauthorized zurückgegeben.

Wenn das Clientprogramm (z. B. die Kalender-App von Apple) eine Sammlung von Principals als Ausgangspunkt erfordert, lautet der URI für die Verbindung:

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

Ersetzen Sie CALENDAR_ID durch die ID des Kalenders, auf den zugegriffen werden soll.

Wenn Sie die Kalender-ID über die Weboberfläche aufrufen möchten, wählen Sie im Drop-down-Menü neben dem Kalendernamen **Kalendereinstellungen** aus. Die Kalender-ID wird im Abschnitt Kalenderadresse angezeigt. Die Kalender-ID für den primären Kalender eines Nutzers ist dieselbe wie die E-Mail-Adresse des Nutzers.

Wenn ein Clientprogramm (z. B. Mozilla Thunderbird) eine Kalendersammlung als Ausgangspunkt erfordert, verwenden Sie den folgenden URI:

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