Zarządzanie kontaktami za pomocą protokołu CardDAV

Możesz wyświetlać swoje kontakty i zarządzać nimi, używając protokołu Google CardDAV.

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

Specyfikacja

Pełna specyfikacja nie jest wdrożona, ale wiele klientów, takich jak Apple iOSTM Contacts i macOS, powinno działać prawidłowo.

W przypadku każdej odpowiedniej specyfikacji pomoc CardDAV Google:

• rfc2518: Rozszerzenia HTTP dla tworzenia rozproszonych (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 funkcji kontroli dostępu WebDAV (rfc3744).
• rfc5995: używanie metody POST do dodawania członków do kolekcji WebDAV
  • Umożliwia tworzenie nowych kontaktów bez określania identyfikatora.
• rfc6352: CardDAV: vCard Extensions to Web Distributed AUTHORs and Webing (WebDAV)
  • Obsługuje metodę HTTP REPORT, ale nie wszystkie zdefiniowane raporty są zaimplementowane.
  • Obsługuje zbiór danych podmiotu zabezpieczeń i kontaktów.
• rfc6578: Synchronizacja kolekcji dla WebDAV
  • Aplikacje klienckie muszą przełączyć się na ten tryb działania po początkowej synchronizacji.
• rfc6749: platforma autoryzacji OAuth 2.0 i rfc6750: schemat autoryzacji OAuth 2.0: wykorzystanie okaziciela
  • Obsługuje uwierzytelnianie programów klienckich CardDAV przy użyciu uwierzytelniania HTTP 2.0. Google nie obsługuje innych metod uwierzytelniania. Aby zapewnić bezpieczeństwo danych kontaktowych, wymagamy połączeń CardDAV z użyciem HTTPS.
• rfc6764: lokalizowanie usług rozszerzeń kalendarza do rozszerzeń WebDAV (CalDAV) i rozszerzeń vCard do WebDAV (CardDAV)
  • Pobieranie adresów URL CardDAV musi odbywać się zgodnie z sekcją 6 w dokumencie rfc6764.
• Obsługuje tag caldav-ctag-02: Calendar Collection Entity Tag (CTag) w CalDAV, który jest wspólny dla specyfikacji CardDAV i CalDAV. Kontakty ctag są jak zasoby ETag. Zmieniają się one, gdy coś zmieni się w książce adresowej. Dzięki temu program kliencki może szybko ustalić, czy nie musi synchronizować żadnych zmienionych kontaktów.
• Google wykorzystuje VCard 3.0 jako format kodowania kontaktów. Zobacz: rfc6350: VCard 3.0.

CardDAV od Google wymaga protokołu OAuth 2.0

Interfejs CardDAV firmy Google wymaga protokołu OAuth 2.0. Więcej informacji o uzyskiwaniu dostępu do interfejsów API Google za pomocą protokołu OAuth 2.0 znajdziesz w powiązanej dokumentacji:

• Uzyskiwanie dostępu do interfejsów API Google przy użyciu protokołu OAuth 2.0
• Korzystanie z protokołu OAuth 2.0 dla zainstalowanych aplikacji

Łączenie z serwerem CardDAV Google

Protokół CardDAV umożliwia wykrywanie identyfikatorów URI książek adresowych i kontaktów. Nie możesz zakodować na stałe żadnych identyfikatorów URI, bo mogą one ulec zmianie w dowolnym momencie.

Aplikacje klienta muszą używać protokołu HTTPS, a na koncie Google użytkownika musi być ustawione uwierzytelnianie OAuth 2.0. Serwer CardDAV nie będzie uwierzytelniać żądania, dopóki nie otrzyma ono protokołu HTTPS z uwierzytelnianiem konta Google za pomocą protokołu OAuth 2.0, a aplikacja zostanie zarejestrowana w DevConsole. Każda próba nawiązania połączenia przez HTTP z uwierzytelnianiem podstawowym lub z adresem e-mail i hasłem niepasującym do konta Google zwraca kod odpowiedzi HTTP 401 Unauthorized.

Aby można było używać CardDAV, program klienta musi początkowo połączyć się ze kanoniczną ścieżką wykrywania, wykonując HTTP PROPFIND na:

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

Po przekierowaniu (HTTP 301) do zasobu książki adresowej Twój program kliencki może wykonać PROPFIND, aby wykryć właściwości DAV:current-user-principal, DAV:principal-URL i addressbook-home-set. Twój program kliencki może następnie wykryć książkę adresową podmiotu zabezpieczeń, wykonując PROPFIND w addressbook-home-set i szukając zasobów addressbook oraz collection. Pełny opis tego procesu jest poza zakresem tego dokumentu. Więcej informacji znajdziesz na stronie rfc6352.

Ścieżka przekierowania zwrócona w odpowiedzi HTTP 301 za pomocą PROPFIND dobrze znanego identyfikatora URI musi nie trwale zostać zapisana w pamięci podręcznej (jak w przypadku rfc6764). Urządzenia powinny okresowo podejmować próbę wykrycia dobrze znanego identyfikatora URI, aby sprawdzić, czy ścieżka do pamięci podręcznej jest nadal aktualna, a następnie ponownie zsynchronizować ją, jeśli ścieżka ulegnie zmianie. Google zaleca częstotliwość co 2–4 tygodnie.

Zasoby

CardDAV wykorzystuje koncepcje REST. Aplikacje klienckie wykorzystują zasoby oznaczone przez ich identyfikatory URI. Obecna struktura identyfikatora URI jest tutaj określona, aby pomóc deweloperom w zrozumieniu zagadnień podanych w sekcji poniżej. Struktura może się zmienić i nie może być zakodowana na stałe. Zasoby powinny być wykrywane zgodnie z RFC.

1. Podmiot zabezpieczeń
   • https://www.googleapis.com/carddav/v1/principals/userEmail
2. Zestaw dla domu
   • 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 przedstawiamy ogólny opis obsługiwanych operacji. Deweloperzy powinni poszukać informacji w odpowiednim RFC. Żądania i odpowiedzi są w większości zakodowane w formacie XML. Oto główne operacje używane przez aplikacje klienckie do synchronizacji:

• Przy użyciu tagu CTag
  • Programy klienckie wykorzystują żądanie getctag PROPFIND z zasobu książki adresowej, aby ustalić, czy na serwerze wprowadzono zmiany lub w związku z tym należy przeprowadzić synchronizację. Wartość tej usługi na pewno zostanie zmieniona, jeśli zmieni się jakikolwiek kontakt. Aplikacje klienckie powinny zapisać tę wartość i używać jej tylko podczas pierwszej synchronizacji oraz jako kreacji zastępczej w przypadku unieważnienia sync-token. Okresowe odpytywanie w usłudze getctag spowoduje ograniczenie.
• Używanie tokena synchronizacji
  • Programy klienta wykorzystują żądanie sync-token PROPFIND w książce adresowej, aby uzyskać sync-token reprezentujące jego bieżący stan. Aplikacje klienckie muszą przechowywać tę wartość i okresowo wysyłać żądania sync-collectionREPORT, aby określić zmiany od ostatniego wysłania.sync-token Przyznane tokeny są ważne przez 29 dni, a odpowiedź REPORT będzie zawierać nowy sync-token.
• Korzystanie z tagów ETag
  • Aplikacje klienckie wysyłają żądanie getetag PROPFIND w zasobie książki adresowej (z nagłówkiem DEPTH równym DEPTH_1). Dzięki zachowaniu wartości ETag każdego kontaktu program kliencki może zażądać wartości kontaktów, których ETag uległ zmianie.
• Pobieranie kontaktów
  • Aplikacje klienckie pobierają kontakty przez wysłanie żądania addressbook-multiget REPORT. Biorąc pod uwagę listę identyfikatorów URI kontaktów, raport zwraca wszystkie żądane kontakty jako wartości VCard 3.0. Każdy wpis zawiera element ETag kontaktu.
• Wstawianie kontaktu
  • Aplikacje klienta 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. Kontakt zostanie zaktualizowany, jeśli kontakt już istnieje w książce adresowej.
  • Aplikacje klienckie powinny zawierać nagłówek If-Match z znanym obecnie kontaktem ETag. Serwer odrzuci wtedy żądanie PUT (z wartością HTTP 412), jeśli obecny ETag na serwerze będzie różnił się od żądania ETag przesłanego przez program kliencki. Umożliwia to optymalizację serializacji aktualizacji.
• Usuwanie kontaktu
  • Aplikacje klienckie usuwają kontakty, wysyłając żądania DELETE przeciwko URI kontaktu.