Przewodnik dla programistów interfejsu CalDAV API

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

Firma Google udostępnia interfejs CalDAV, który umożliwia wyświetlanie kalendarzy i zarządzanie nimi przy użyciu protokołu CalDAV.

Specyfikacja

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

  • rfc4918: rozszerzenia HTTP dla tworzenia i obsługi wersji rozproszonych w sieci (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. Są zaimplementowane wszystkie raporty z wyjątkiem zapytania o stan Wolny/Zajęty.
    • 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 Apple iCal®, które pozwala na ustawianie właściwości adresów URL przez użytkownika.
  • rfc6578: synchronizacja kolekcji dla WebDAV
    • Aplikacje klienckie muszą przełączyć się na ten tryb po pierwszej synchronizacji.
  • rfc6638: Planowanie rozszerzeń do protokołu CalDAV
    • Obsługuje prostą „skrzynkę odbiorczą”, która jest zawsze pusta.
    • Zaproszenia, które otrzymujesz, są automatycznie dostarczane do kolekcji „Wydarzenia” – nie są umieszczane w „skrzynce odbiorczej”.
    • Nie obsługuje wyszukiwania informacji o stanie Wolny/Zajęty.
  • caldav-ctag-02: tag jednostki kolekcji Kalendarza (CTag) w CalDAV
    • Kalendarz ctag jest jak zasób etag i zmienia się, gdy coś się w nim zmieni. Dzięki temu aplikacja kliencka może szybko określić, że nie musi synchronizować żadnych zmienionych zdarzeń.
  • calendar-proxy: Funkcje serwera proxy Kalendarza użytkownika w CalDAV
    • Aby poprawić wydajność synchronizacji kalendarza na urządzeniach z iOS, które nie obsługują przekazywania dostępu, użycie właściwości calendar-proxy-read-for lub calendar-proxy-write-for z klientem użytkownika iOS zakończy się niepowodzeniem.

Nie wprowadziliśmy jeszcze w pełni implementacji wszystkich istotnych specyfikacji. Jednak w przypadku wielu klientów, takich jak Apple iCal, protokół CalDAV powinien współpracować prawidłowo.

Uwaga: ze względu na bezpieczeństwo konta i zapobieganie nadużyciom Google może ustawiać pliki cookie w aplikacjach klienckich, które uzyskują dostęp do danych przez CalDAV.

Tworzę identyfikator klienta

Aby korzystać z interfejsu CalDAV API, musisz mieć konto Google. Jeśli masz już konto, z którego możesz korzystać, nie musisz nic robić.

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.

Następnym krokiem jest aktywowanie interfejsu CalDAV API.

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

  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. W bibliotece interfejsów API wymienione są wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności.
  2. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, znajdź go za pomocą wyszukiwania.
  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 wykonywać żądania do interfejsu CalDAV API, potrzebujesz Client-ID i Client Secret.

Aby znaleźć identyfikator klienta i tajny klucz klienta projektu, wykonaj te czynności:

  1. Wybierz istniejące dane logowania OAuth 2.0 lub otwórz stronę Dane logowania.
  2. Utwórz dane uwierzytelniające projektu OAuth 2.0, klikając Utwórz dane logowania > Identyfikator klienta OAuth, i podaj informacje potrzebne do utworzenia danych logowania.
  3. W sekcji Identyfikatory klienta OAuth 2.0 odszukaj pole Identyfikator klienta. Aby uzyskać szczegółowe informacje, kliknij identyfikator klienta.

Nawiązywanie połączenia z serwerem CalDAV Google

Aby skorzystać z interfejsu CalDAV, program kliencki wstępnie łączy się z serwerem kalendarza w jednym z dwóch punktów początkowych. W obu przypadkach połączenie musi być nawiązywane przez protokół HTTPS i używać schematu uwierzytelniania protokołu OAuth 2.0. Serwer CalDAV odmówi uwierzytelnienia żądania, chyba że zostanie ono odebrane przez protokół HTTPS z uwierzytelnianiem OAuth 2.0 konta Google. Próba połączenia przez HTTP lub użycie uwierzytelniania podstawowego powoduje wyświetlenie kodu stanu HTTP 401 Unauthorized.

Jeśli program kliencki (np. Apple iCal) wymaga podstawowego zbioru danych jako punktu początkowego, identyfikator URI, z którym należy się połączyć, to:

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

Gdzie calid należy zastąpić „identyfikatorem kalendarza” kalendarza, do którego chcesz uzyskać dostęp. Możesz go znaleźć w interfejsie internetowym Kalendarza Google w następujący sposób: w menu obok nazwy kalendarza wybierz Ustawienia kalendarza. Na wyświetlonej stronie identyfikator kalendarza będzie widoczny w sekcji Adres kalendarza. Identyfikator kalendarza głównego kalendarza użytkownika jest taki sam jak adres e-mail tego użytkownika.

Jeśli program kliencki (np. Mozilla Sunbird) wymaga zbioru kalendarza jako punktu początkowego, identyfikator URI, z którym należy się połączyć, 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. Korzystasz z niego na własne ryzyko. Zalecamy przejście na nowy format punktów końcowych opisany powyżej.

iCal jest znakiem towarowym firmy Apple Inc.