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.

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 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: Calendaring Extensions to WebDAV (CalDAV)
    • Obsługuje metodę HTTP REPORT. Wszystkie raporty oprócz raportu 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ą sformatowane zgodnie ze specyfikacją iCalendar.
    • Obecnie nie obsługuje danych VTODO ani VJOURNAL.
    • Nie obsługuje rozszerzenia Apple iCal®, które umożliwia użytkownikom ustawianie właściwości URL.
  • rfc6578: Collection Synchronization for WebDAV
    • Aplikacje klienckie muszą przejść do tego trybu działania po pierwszej synchronizacji.
  • 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 informacji o dostępności.
  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV
    • Kalendarz ctag jest podobny do zasobu etag. Zmienia się, gdy w kalendarzu nastąpią jakiekolwiek zmiany. Dzięki temu aplikacja kliencka może szybko stwierdzić, że nie musi synchronizować żadnych zmienionych zdarzeń.
  • calendar-proxy: Calendar User Proxy Functionality in CalDAV
    • Aby zwiększyć wydajność synchronizacji kalendarza z urządzeń z iOS, które nie obsługują delegowania, użycie właściwości calendar-proxy-read-for lub calendar-proxy-write-for z ciągiem UserAgent systemu iOS zakończy się niepowodzeniem.

Nie wdrożyliśmy jeszcze w pełni wszystkich odpowiednich specyfikacji. W przypadku wielu klientów, np. aplikacji Kalendarz od Apple, protokół CalDAV powinien jednak działać prawidłowo.

Uwaga: ze względu na bezpieczeństwo konta i aby zapobiegać nadużyciom, Google może ustawiać pliki cookie w aplikacjach klienckich, które uzyskują dostęp do danych za pomocą 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ć, nie musisz nic więcej robić.

Zanim zaczniesz 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 aktywacja interfejsu CalDAV API.

Aby włączyć interfejs API w projekcie:

  1. Otwórz Bibliotekę 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, użyj wyszukiwarki, aby go znaleźć.
  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 do CalDAV API, potrzebujesz identyfikatora klienta i tajnego klucza klienta.

Aby znaleźć identyfikator 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 odmówi uwierzytelnienia żądania, chyba że zostanie ono przesłane 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/calid/user

gdzie calid należy zastąpić „identyfikatorem kalendarza”, do którego chcesz uzyskać dostęp. Możesz to zrobić w interfejsie internetowym Kalendarza Google: w menu obok nazwy kalendarza wybierz Ustawienia kalendarza. Na stronie, która się otworzy, identyfikator kalendarza będzie widoczny w sekcji Adres kalendarza. Identyfikator kalendarza podstawowego użytkownika jest taki sam jak jego adres e-mail.

Jeśli program kliencki (np. Mozilla Sunbird) wymaga kolekcji kalendarzy 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. Korzystasz 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.