Przewodnik dla programistów interfejsu CalDAV API

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

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 protokołu CalDAV Google jest następująca:

• rfc4918: rozszerzenia HTTP do tworzenia i obsługi wersji w sieci rozproszonej (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. implementowane są wszystkie raporty z wyjątkiem zapytania o stanie Wolny/Zajęty.
  • Nie obsługuje metody HTTP MKCALENDAR.
  • Nie obsługuje czynności AUDIO.
• rfc5545: iKalendarz
  • Dane udostępniane w interfejsie CalDAV są formatowane zgodnie ze specyfikacją iKalendarza.
  • Obecnie nie obsługuje danych VTODO ani VJOURNAL.
  • Rozszerzenie Apple iCal® nie obsługuje właściwości adresów URL możliwych do ustawienia przez użytkownika.
• rfc6578: Collection Synchronization for WebDAV
  • Aplikacje klienckie muszą przełączyć się na ten tryb działania po początkowej synchronizacji.
• rfc6638: planowanie rozszerzeń do CalDAV
  • Obsługuje prostą „skrzynkę odbiorczą”, która zawsze jest pusta.
  • Zaproszenia, które otrzymasz, będą dostarczane automatycznie do kolekcji „wydarzenia”, a nie do „skrzynki odbiorczej”.
  • Wyszukiwanie informacji o stanie Wolny/Zajęty nie jest obsługiwane.
• caldav-ctag-02: tag CTag (CTag) kalendarza w CalDAV
  • Kalendarz ctag jest jak zasób etag i zmienia się, gdy cokolwiek w kalendarzu się zmienia. Dzięki temu aplikacja kliencka może szybko stwierdzić, że nie musi synchronizować żadnych zmienionych zdarzeń.
• calendar-proxy: Funkcje serwera proxy użytkowników Kalendarza 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 udostępniliśmy jeszcze pełnej implementacji wszystkich odpowiednich specyfikacji. Jednak w przypadku wielu klientów, takich jak aplikacja Kalendarz Apple, protokół CalDAV powinien współdziałać prawidłowo.

Uwaga: ze względu na bezpieczeństwo konta i zapobieganie nadużyciom Google może umieszczać 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 zaczniesz wysyłać żądania do interfejsu CalDAV API, musisz zarejestrować klienta w Konsoli interfejsów API Google przez utworzenie projektu.

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ę API w konsoli interfejsów API Google. Jeśli pojawi się taka prośba, wybierz projekt lub utwórz nowy. Zawiera ona 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 za pomocą wyszukiwarki.
3. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
4. Włącz płatności, jeśli pojawi się taka prośba.
5. Jeśli pojawi się taka prośba, zaakceptuj Warunki korzystania z usługi API.

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

Aby znaleźć identyfikator 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 logowania OAuth 2.0 projektu, klikając Utwórz dane logowania > Identyfikator klienta OAuth, i podaj informacje potrzebne do utworzenia danych logowania.
3. Odszukaj Identyfikator klienta w sekcji Identyfikatory klienta OAuth 2.0. Aby wyświetlić szczegółowe informacje, kliknij identyfikator klienta.

Łączenie z serwerem CalDAV Google

Aby można było używać interfejsu CalDAV, program kliencki początkowo łączy się z serwerem kalendarza w jednym z dwóch 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 za pomocą protokołu HTTPS z uwierzytelnianiem OAuth 2.0 konta Google. Próba połączenia przez HTTP lub użycie uwierzytelniania podstawowego zwraca kod stanu HTTP 401 Unauthorized.

Jeśli program kliencki (np. aplikacja Kalendarz firmy Apple) wymaga jako punktu początkowego zbierania danych przez podmiot zabezpieczeń, identyfikator URI, z którym ma zostać nawiązane połączenie, 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. Ten interfejs jest dostępny w interfejsie internetowym Kalendarza Google w następujący sposób: w menu obok nazwy kalendarza wybierz Ustawienia kalendarza. Na stronie wynikowej identyfikator kalendarza będzie widoczny w sekcji Adres kalendarza. Identyfikator kalendarza głównego użytkownika jest taki sam jak jego adres e-mail.

Jeśli program kliencki (taki jak Mozilla Sunbird) wymaga zbierania danych z kalendarza jako punktu początkowego, identyfikator URI, z którym ma zostać nawiązane połączenie:

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. Używaj go na własne ryzyko. Zalecamy przejście na nowy format punktów końcowych opisany powyżej.

iCal® jest znakiem towarowym firmy Apple Inc.