Przewodnik dla programistów interfejsu CalDAV API

CalDAV to rozszerzenie WebDAV, które zapewnia klientom dostęp do informacji o kalendarzu na serwerze zdalnym.

Google udostępnia interfejs CalDAV, którego możesz używać do wyświetlania kalendarzy i zarządzania nimi za pomocą protokołu CalDAV.

Interfejs CalDAV API ma takie same limity jak interfejs Calendar API. Więcej informacji znajdziesz w artykule Limity użycia.

Specyfikacja

W przypadku każdej z odpowiednich specyfikacji obsługa CalDAV przez Google jest następująca:

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

    • Obsługuje metody HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND i PROPPATCH.
    • Nie obsługuje metod HTTP LOCK, UNLOCK, COPY, MOVE, MKCOL, ani nagłówka If* (z wyjątkiem If-Match).
    • Nie obsługuje dowolnych (zdefiniowanych przez użytkownika) właściwości WebDAV.
    • Nie obsługuje kontroli dostępu WebDAV (rfc3744).

  • rfc4791: Calendaring Extensions to WebDAV (CalDAV)

    • Obsługuje metodę HTTP REPORT. Wszystkie raporty oprócz free-busy-query są zaimplementowane.
    • Nie obsługuje metody HTTP MKCALENDAR.
    • Nie obsługuje działania AUDIO.

  • rfc5545: iCalendar

    • Dane udostępniane w interfejsie CalDAV są formatowane zgodnie ze specyfikacją iCalendar.
    • Nie obsługuje danych VTODO ani VJOURNAL.
    • Nie obsługuje rozszerzenia Apple iCal, które umożliwia ustawianie przez użytkownika właściwości URL.

  • rfc6578: Collection Synchronization for WebDAV

    • Po wstępnej synchronizacji aplikacje klienckie muszą przejść na ten tryb działania.

  • rfc6638: Scheduling Extensions to CalDAV

    • Obsługuje trywialną „skrzynkę odbiorczą”, która jest zawsze pusta.
    • Otrzymywane zaproszenia są automatycznie dostarczane do kolekcji „wydarzenia”, a nie do „skrzynki odbiorczej”.
    • Nie obsługuje wyszukiwania free-busy.

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

    • ctag kalendarza jest podobny do etag zasobu – zmienia się, gdy zmieni się cokolwiek w kalendarzu. Dzięki temu aplikacja kliencka może szybko stwierdzić, że nie musi synchronizować żadnych zmienionych wydarzeń.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • Aby poprawić wydajność synchronizacji kalendarza, żądania zawierające właściwości calendar-proxy-read-for lub calendar-proxy-write-for będą kończyć się niepowodzeniem w przypadku UserAgenta iOS, ponieważ urządzenia z iOS nie obsługują delegowania.

Chociaż nasza implementacja CalDAV nie obejmuje wszystkich specyfikacji, działa prawidłowo w przypadku wielu klientów, w tym Kalendarza Apple.

Tworzenie identyfikatora klienta

Aby korzystać z interfejsu CalDAV API, musisz mieć konto Google.

Zanim zaczniesz wysyłać żądania do interfejsu CalDAV API, musisz zarejestrować swojego klienta w konsoli Google Cloud, tworząc projekt.

Otwórz konsolę interfejsów API Google. Kliknij Utwórz projekt, wpisz nazwę i kliknij Utwórz.

Następnie musisz aktywować interfejs CalDAV API.

Aby włączyć interfejs API w projekcie:

  1. Otwórz bibliotekę interfejsów API w konsoli interfejsów API Google. Jeśli pojawi się taka prośba, wybierz projekt lub utwórz nowy. Biblioteka API zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według rodziny produktów i popularności.
  2. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, użyj wyszukiwarki.
  3. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
  4. Jeśli pojawi się taka prośba, włącz płatności.
  5. Jeśli pojawi się taka prośba, zaakceptuj Warunki korzystania z interfejsu API.

Aby wysyłać żądania do interfejsu CalDAV API , potrzebujesz identyfikatora klienta i tajnego klucza klienta.

Aby znaleźć identyfikator klienta i tajny klucz klienta projektu:

  1. Wybierz istniejące dane logowania OAuth 2.0 lub otwórz stronę Dane logowania.
  2. Jeśli jeszcze tego nie zrobiono, utwórz dane logowania OAuth 2.0 projektu, klikając Utwórz dane logowania > Identyfikator klienta OAuth i podając informacje potrzebne do utworzenia danych logowania.
  3. W sekcji Identyfikatory klienta OAuth 2.0 znajdź identyfikator klienta. Aby uzyskać szczegółowe informacje, kliknij identyfikator klienta.

Łączenie z serwerem CalDAV Google

Aby korzystać z interfejsu CalDAV, program kliencki początkowo łączy się z serwerem kalendarza w jednym z 2 punktów początkowych. W obu przypadkach połączenie musi być nawiązywane przez HTTPS i musi używać schematu uwierzytelniania OAuth 2.0. Serwer CalDAV odmawia uwierzytelnienia żądania, chyba że dotrze ono przez HTTPS z uwierzytelnianiem OAuth 2.0 konta Google. Próba połączenia przez HTTP lub przy użyciu uwierzytelniania podstawowego powoduje zwrócenie kodu stanu HTTP 401 Unauthorized.

Jeśli program kliencki (np. aplikacja Kalendarz Apple) wymaga kolekcji głównej jako punktu początkowego, identyfikator URI, z którym należy się połączyć, to:

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

Zastąp CALENDAR_ID identyfikatorem kalendarza, do którego chcesz uzyskać dostęp.

Aby znaleźć identyfikator kalendarza w interfejsie internetowym, w menu obok nazwy kalendarza wybierz **Ustawienia kalendarza**. Identyfikator kalendarza jest widoczny w sekcji Adres kalendarza. Identyfikator kalendarza głównego użytkownika jest taki sam jak jego adres e-mail.

Jeśli program kliencki (np. Mozilla Thunderbird) wymaga kolekcji kalendarza jako punktu początkowego, użyj tego identyfikatora URI:

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