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óry umożliwia wyświetlanie kalendarzy i zarządzanie nimi za pomocą protokołu CalDAV.

Specyfikacja

W przypadku każdej z odpowiednich specyfikacji obsługa CalDAV przez Google wygląda tak:

  • 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 ani 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: Rozszerzenia kalendarza do WebDAV (CalDAV)
    • Obsługuje metodę HTTP REPORT. Wdrożone są wszystkie raporty oprócz zapytania o dostępność.
    • 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.
    • Obecnie nie obsługuje danych VTODO ani VJOURNAL.
    • Nie obsługuje rozszerzenia iCal® firmy Apple, które umożliwia użytkownikom ustawianie właściwości adresu URL.
  • rfc6578: synchronizacja kolekcji w usłudze WebDAV
    • Po początkowej synchronizacji aplikacje klienckie muszą przejść w 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 folderu „Skrzynka odbiorcza”.
    • Nie obsługuje wyszukiwania informacji o dostępności.
  • caldav-ctag-02: tag elementu kolekcji kalendarza (CTag) w CalDAV
    • Kalendarz ctag jest jak zasób etag: zmienia się, gdy zmieni się cokolwiek w kalendarzu. Dzięki temu aplikacja kliencka może szybko ustalić, że nie musi synchronizować żadnych zmienionych zdarzeń.
  • calendar-proxy: funkcja proxy użytkownika w CalDAV
    • Aby zwiększyć wydajność synchronizacji kalendarza na urządzeniach z iOS, które nie obsługują delegowania, nie należy używać właściwości calendar-proxy-read-for ani calendar-proxy-write-for z identyfikatorem użytkownika iOS.

Nie wprowadziliśmy jeszcze wszystkich odpowiednich specyfikacji. Jednak w przypadku wielu klientów, takich jak aplikacja Kalendarz Apple, protokół CalDAV powinien działać prawidłowo.

Uwaga: ze względu na bezpieczeństwo konta i aby zapobiec nadużyciom Google może zapisywać pliki cookie w aplikacjach klienckich, które uzyskują dostęp do danych za pomocą protokołu CalDAV.

Tworzenie identyfikatora klienta

Aby korzystać z interfejsu CalDAV API, musisz mieć konto Google. Jeśli masz już konto, którego możesz używać, to wszystko.

Zanim będzie można wysyłać żądania do interfejsu CalDAV API, musisz zarejestrować klienta w Konsoli interfejsów API Google, tworząc projekt.

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

Kolejnym krokiem jest aktywowanie interfejsu CalDAV API.

Aby włączyć interfejs API w projekcie, wykonaj te czynności:

  1. Otwórz Bibliotekę API w konsoli interfejsów API Google. Jeśli pojawi się taka prośba, wybierz projekt lub utwórz nowy. Biblioteka interfejsów 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, znajdź go za pomocą 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 usługi interfejsu API.
Aby wykonywać żądania interfejsu CalDAV API, musisz mieć identyfikator klienta i tajny klucz 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 uwierzytelniające OAuth 2.0 projektu, klikając Utwórz dane uwierzytelniające > Identyfikator klienta OAuth i podając informacje potrzebne do utworzenia danych uwierzytelniających.
  3. W sekcji Identyfikatory klienta OAuth 2.0 odszukaj Identyfikator klienta. Aby uzyskać szczegółowe informacje, kliknij identyfikator klienta.

Łączenie z serwerem CalDAV Google

Aby korzystać z interfejsu CalDAV, program klienta łączy się początkowo z serwerem kalendarza w jednym z dwóch punktów początkowych. W obu przypadkach połączenie musi być nawiązywane przez HTTPS i wykorzystywać schemat uwierzytelniania OAuth 2.0. Serwer CalDAV odmówi uwierzytelnienia żądania, jeśli nie zostanie ono przesłane przez HTTPS z uwierzytelnieniem OAuth 2.0 konta Google. Próba połączenia przez HTTP lub użycie uwierzytelniania podstawowego powoduje kod stanu HTTP 401 Unauthorized.

Jeśli program kliencki (np. aplikacja Kalendarz Apple) wymaga, aby punktem wyjścia była główna kolekcja, identyfikator URI do połączenia to:

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

Gdzie calid należy zastąpić identyfikatorem „calendar ID” kalendarza, do którego chcesz uzyskać dostęp. Aby znaleźć te informacje w interfejsie internetowym Kalendarza Google, wykonaj te czynności: w menu rozwijanym obok nazwy kalendarza kliknij Ustawienia Kalendarza. Na wyświetlonej stronie 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 klienta (np. Mozilla Sunbird) wymaga zbioru kalendarza jako punktu wyjścia, identyfikator URI do połączenia to:

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

Stary punkt końcowy https://www.google.com/calendar/dav został wycofany i nie jest już obsługiwany. Korzystaj z niego na własne ryzyko. Zalecamy przejście na nowy format punktu końcowego opisany powyżej.

iCal® jest znakiem towarowym firmy Apple Inc.