Zarządzanie kontaktami za pomocą protokołu CardDAV

Możesz wyświetlać kontakty i zarządzać nimi przy użyciu protokołu Google CardDAV.

Kontakty są przechowywane na koncie Google użytkownika. Do listy kontaktów ma dostęp większość usług Google. Aplikacja kliencka może używać interfejsu CardDAV API do tworzenia nowych kontaktów, edytowania i usuwania istniejących oraz wysyłania zapytań o kontakty spełniające określone kryteria.

Specyfikacja

Nie wdrożono pełnej specyfikacji, ale wiele klientów, np. Apple iOSTM Kontakty i macOS, powinno współpracować prawidłowo.

W przypadku każdej odpowiedniej specyfikacji Google obsługuje CardDAV w następujący sposób:

• rfc2518: rozszerzenia HTTP dla tworzenia rozproszonego (WebDAV)
  • Obsługuje metody HTTP GET, PUT, DELETE, OPTIONS i PROPFIND.
  • Nie obsługuje metod HTTP LOCK, UNLOCK, COPY, MOVE ani MKCOL.
  • Nie obsługuje dowolnych (zdefiniowanych przez użytkownika) właściwości WebDAV.
  • Nie obsługuje kontroli dostępu WebDAV (rfc3744).
• rfc5995: dodawanie członków do kolekcji WebDAV przy użyciu metody POST
  • Umożliwia tworzenie nowych kontaktów bez określania identyfikatora.
• rfc6352: CardDAV: narzędzie do tworzenia wersji i tworzenia wersji rozproszonych za pomocą rozszerzeń go w przeglądarce (WebDAV)
  • Obsługuje metodę HTTP REPORT, ale nie wszystkie zdefiniowane raporty są implementowane.
  • Obsługuje kolekcję podmiotów zabezpieczeń i kolekcję kontaktów.
• rfc6578: synchronizacja kolekcji dla WebDAV
  • Aplikacje klienckie muszą przełączyć się na ten tryb po pierwszej synchronizacji.
• rfc6749: OAuth 2.0 Authorization Framework i rfc6750: OAuth 2.0 Authorization Framework: Bearer Token Usage
  • Obsługuje uwierzytelnianie programów klienckich CardDAV przy użyciu uwierzytelniania HTTP OAuth 2.0. Google nie obsługuje żadnej innej metody uwierzytelniania. Ze względu na bezpieczeństwo danych kontaktów wymagamy, aby połączenia CardDAV korzystały z HTTPS.
• rfc6764: lokalizowanie usług dla rozszerzeń kalendarza w WebDAV (CalDAV) i rozszerzenia kart eSIM do WebDAV (CardDAV)
  • Wczytywanie adresów URL CardDAV musi odbywać się zgodnie z sekcją 6 dokumentu rfc6764.
• Obsługuje caldav-ctag-02: tag CTag kolekcji kalendarza w CalDAV, który jest wspólny dla specyfikacji CardDAV i CalDAV. Kontakty ctag są jak zasób ETag i zmieniają się, gdy zmieni się coś w kontaktowej książce adresowej. Dzięki temu program kliencki może szybko stwierdzić, że nie musi synchronizować żadnych zmienionych kontaktów.
• Google używa formatu kodowania kontaktów VCard 3.0. Zobacz: rfc6350: VCard 3.0.

CardDAV firmy Google wymaga protokołu OAuth 2.0

Interfejs Google CardDAV wymaga protokołu OAuth 2.0. Więcej informacji o używaniu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google znajdziesz w poniższej dokumentacji:

• Korzystanie z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google
• Używanie protokołu OAuth 2.0 w zainstalowanych aplikacjach

Łączę z serwerem CardDAV Google

Protokół CardDAV umożliwia wykrywanie identyfikatorów URI książki adresowej i zasobów kontaktowych. Identyfikator URI nie może być kodowany na stałe, ponieważ mogą się one zmienić w dowolnym momencie.

Aplikacje klienckie muszą używać protokołu HTTPS, a konto Google użytkownika musi mieć uwierzytelnianie OAuth 2.0. Serwer CardDAV nie uwierzytelni żądania, jeśli nie zostanie ono odebrane przez protokół HTTPS z uwierzytelnieniem konta Google za pomocą protokołu OAuth 2.0, a aplikacja jest zarejestrowana w konsoli DevConsole. Każda próba połączenia się przez HTTP z uwierzytelnianiem podstawowym lub z użyciem adresu e-mail i hasła niezgodnych z kontem Google skutkuje wysłaniem kodu odpowiedzi HTTP 401 Unauthorized.

Aby korzystać z CardDAV, Twój program kliencki musi wstępnie połączyć się ze ścieżką wykrywania kanonicznego, wykonując żądanie HTTP PROPFIND na stronie:

https://www.googleapis.com/.well-known/carddav

Po przekierowaniu (HTTP 301) do zasobu książki adresowej Twój program klienta może wykonać na nim polecenie PROPFIND, aby wykryć właściwości DAV:current-user-principal, DAV:principal-URL i addressbook-home-set. Program dla klientów może następnie wykryć główną książkę adresową, wykonując polecenie PROPFIND w addressbook-home-set i wyszukując zasoby addressbook i collection. Pełny opis tego procesu wykracza poza zakres tego dokumentu. Więcej informacji znajdziesz w rfc6352.

Ścieżka przekierowania zwracana w odpowiedzi HTTP 301 za pomocą PROPFIND w dobrze znanym identyfikatorze URI nie może być trwale przechowywana w pamięci podręcznej (zgodnie z rfc6764). Urządzenia powinny okresowo powtarzać wykrywanie dobrze znanych identyfikatorów URI, aby sprawdzić, czy ścieżka w pamięci podręcznej jest nadal aktualna, i w razie zmiany ścieżki dokonać ponownej synchronizacji. Google zaleca rozliczanie się co 2–4 tygodnie.

Zasoby

CardDAV korzysta z pojęć REST. Aplikacje klienckie korzystają z zasobów oznaczonych ich identyfikatorami URI. Podano tutaj obecną strukturę URI, aby ułatwić programistom zrozumienie pojęć opisanych w następnej sekcji. Struktura może się zmienić i nie może być kodowana na stałe. Zasoby powinny być wykrywane zgodnie z dokumentem RFC.

1. Podmiot zabezpieczeń
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Zestaw domowy
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
3. Książka adresowa
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
4. Kontakt
   • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

Synchronizowanie kontaktów

Poniżej znajdziesz ogólny opis obsługiwanych operacji. Deweloperzy powinni poszukać szczegółowych informacji w odpowiednim dokumencie RFC. Żądania i odpowiedzi są w większości kodowane w formacie XML. Aplikacje klienckie używają głównych operacji do synchronizacji:

• Używanie CTag
  • Programy klienckie używają żądania getctag PROPFIND do zasobu książki adresowej, aby określić, czy którykolwiek kontakt zmienił się na serwerze, i w związku z tym czy potrzebna jest synchronizacja. Wartość tej właściwości z pewnością się zmieni, jeśli zmieni się jakiś kontakt. Aplikacje klienckie powinny przechowywać tę wartość i używać jej tylko podczas początkowej synchronizacji oraz jako kreacji zastępczej, gdy sync-token zostanie unieważniony. Okresowe odpytywanie właściwości getctag spowoduje ograniczanie.
• Używanie tokena synchronizacji
  • Programy klienta korzystają z żądania sync-token PROPFIND w książce adresowej, aby uzyskać parametr sync-token wskazujący jego bieżący stan. Aplikacje klienckie muszą przechowywać tę wartość i wysyłać okresowe żądania sync-collection REPORT, aby określić zmiany od ostatniego wydania sync-token. Wydane tokeny są ważne przez 29 dni, a odpowiedź REPORT będzie zawierać nową wartość sync-token.
• Używanie tagów ETag
  • Aplikacje klienckie wysyłają żądanie getetag PROPFIND do zasobu książki adresowej (z nagłówkiem DEPTH równym DEPTH_1). Zachowując wartość ETag każdego kontaktu, program kliencki może zażądać wartości kontaktów, których wartość ETag została zmieniona.
• Pobieranie kontaktów
  • Aplikacje klienckie pobierają kontakty, wysyłając żądanie addressbook-multiget REPORT. Biorąc pod uwagę listę identyfikatorów URI kontaktów, raport zwraca wszystkie żądane kontakty w postaci wartości VCard 3.0. Każdy wpis zawiera ETag odpowiedniego kontaktu.
• Wstawianie kontaktu
  • Aplikacje klienckie wysyłają żądanie POST do nowego kontaktu w formacie VCard 3.0. Odpowiedź będzie zawierać identyfikator nowego kontaktu.
• Aktualizowanie kontaktu
  • Aplikacje klienckie wysyłają żądanie PUT ze zaktualizowanym kontaktem w formacie VCard 3.0. Jeśli kontakt istnieje już w książce adresowej, zostanie zaktualizowany.
  • Aplikacje klienckie powinny zawierać nagłówek If-Match z obecnie znanym identyfikatorem ETag kontaktu. Serwer odrzuci wtedy żądanie PUT (z HTTP 412), jeśli bieżąca wartość ETag na serwerze różni się od żądania ETag wysłanego przez program klienta. Pozwala to zoptymalizować serializację aktualizacji.
• Usuwanie kontaktu
  • Aplikacje klienckie usuwają kontakt, wysyłając żądanie DELETE zamiast identyfikatora URI kontaktu.