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 sekcji Limity wykorzystania.

Specyfikacja

W przypadku każdej z odpowiednich specyfikacji obsługa CalDAV w Google wygląda następująco:

  • 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-queryzostały wdrożone.
    • Nie obsługuje metody HTTP MKCALENDAR.
    • Nie obsługuje działania AUDIO.

  • rfc5545: iCalendar

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

  • rfc6578: Collection Synchronization for WebDAV

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

  • rfc6638: Scheduling Extensions to CalDAV

    • Obsługuje prostą „skrzynkę odbiorczą”, która jest zawsze pusta.
    • Otrzymane 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

    • Kalendarz ctag jest podobny do zasobu etag. 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: funkcje serwera proxy użytkownika Kalendarza w 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 systemem iOS nie obsługują delegowania.

Nasza implementacja CalDAV nie obejmuje wszystkich specyfikacji, ale 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ć 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ć 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ę odpowiedni komunikat, wybierz projekt lub utwórz nowy. W bibliotece interfejsów API znajdziesz wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności.
  2. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, wyszukaj go.
  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 usługi API.

Aby wysyłać żądania 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 łączy się początkowo z serwerem kalendarza w jednym z 2 punktów początkowych. W obu przypadkach połączenie musi być nawiązywane przez HTTPS i musi korzystać ze schematu uwierzytelniania OAuth 2.0. Serwer CalDAV odmawia uwierzytelnienia żądania, chyba że przyjdzie ono przez HTTPS z uwierzytelnianiem OAuth 2.0 konta Google. Próba połączenia przez HTTP lub użycie uwierzytelniania podstawowego powoduje zwrócenie kodu stanu HTTP 401 Unauthorized.

Jeśli program kliencki (np. aplikacja Kalendarz od Apple) wymaga kolekcji głównej jako punktu początkowego, identyfikator URI do połączenia 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 kalendarzy jako punktu początkowego, użyj tego identyfikatora URI:

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