Zarządzanie kontaktami za pomocą protokołu CardDAV

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

kontakty są przechowywane na koncie Google użytkownika; większość usług Google dostępu do listy kontaktów. Aplikacja kliencka może używać interfejsu CardDAV API do tworzenie nowych kontaktów, edytowanie i usuwanie istniejących kontaktów oraz wysyłanie zapytań o kontakty spełniających określone kryteria.

Specyfikacja

Nie wdrożono pełnej specyfikacji, ale wiele klientów, takich jak Kontakty Apple iOSTM i macOS powinny współpracować poprawnie.

W przypadku każdej odpowiedniej specyfikacji obsługa CardDAV przez Google wygląda tak:

• rfc2518: rozszerzenia HTTP do tworzenia rozproszonego (WebDAV)
  • Obsługuje metody HTTP GET, PUT, DELETE, OPTIONS i PROPFIND.
  • Nie obsługuje metod HTTP LOCK, UNLOCK, COPY, MOVE ani MKCOL
  • Dowolne (zdefiniowane przez użytkownika) właściwości WebDAV nie są obsługiwane.
  • Nie obsługuje kontroli dostępu WebDAV (rfc3744).
• rfc5995: używanie POST do dodawania użytkowników do kolekcji WebDAV
  • Umożliwia tworzenie nowych kontaktów bez określania identyfikatora.
• rfc6352: CardDAV: rozszerzenia vCard do Web Distributed Authoring and Obsługa wersji (WebDAV)
  • Obsługuje metodę HTTP REPORT, ale nie wszystkie zdefiniowane raporty są .
  • Umożliwia udostępnianie zbioru podmiotów zabezpieczeń i kolekcji kontaktów.
• rfc6578: Collection Synchronization for WebDAV
  • Aplikacje klienckie muszą przełączyć się na ten tryb działania po synchronizacji początkowej.
• rfc6749: platforma autoryzacji OAuth 2.0 oraz rfc6750: platforma autoryzacji OAuth 2.0 – wykorzystanie tokena okaziciela
  • Obsługuje uwierzytelnianie programów klienta CardDAV za pomocą protokołu HTTP OAuth 2.0 Uwierzytelnianie. Google nie obsługuje żadnych innych metod uwierzytelniania. Ze względu na bezpieczeństwo danych kontaktów połączenia CardDAV wymagają użycia HTTPS.
• rfc6764: Locating Services for Kalendarzing Extensions to WebDAV (CalDAV) i rozszerzenia vCard do WebDAV (CardDAV).
  • Wczytywanie adresów URL CardDAV musi odbywać się zgodnie z sekcją 6 rfc6764.
• Obsługiwane caldav-ctag-02: tag CTag (CTag) kalendarza w CalDAV, który jest wspólny dla specyfikacji CardDAV i CalDAV. Kontakty ctag jest jak zasób ETag; zmienia się, gdy cokolwiek w kontakcie książka adresowa została zmieniona. Dzięki temu program klienta może szybko określić, że nie trzeba synchronizować żadnych zmienionych kontaktów.
• Google używa formatu VCard 3.0 do kodowania kontaktów. Zobacz: rfc6350: VCard 3.0.

CardDAV Google wymaga protokołu OAuth 2.0

Interfejs Google CardDAV wymaga protokołu OAuth 2.0. Skorzystaj z linku poniżej znajdziesz informacje o tym, jak uzyskiwać dostęp do interfejsów API Google przy użyciu protokołu OAuth 2.0:

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

Łączenie z serwerem CardDAV Google

Protokół CardDAV umożliwia wykrywanie książki adresowej i zasobów kontaktów Identyfikatory URI. Nie możesz kodować identyfikatorów URI na stałe, ponieważ mogą się one w każdej chwili zmienić.

Aplikacje klienckie muszą używać protokołu HTTPS, a uwierzytelnianie OAuth 2.0 musi być podany na koncie Google użytkownika. Serwer CardDAV nie będzie uwierzytelniać żądania, chyba że są one dostarczane za pośrednictwem protokołu HTTPS i protokołu OAuth 2.0. uwierzytelnienie konta Google, a Twoja aplikacja jest DevConsole. Każda próba połączenia przez HTTP z uwierzytelnianiem podstawowym lub z adres e-mail/hasło niezgodne z kontem Google powoduje wyświetlenie HTTP Kod odpowiedzi 401 Unauthorized.

Aby można było używać CardDAV, program kliencki musi początkowo połączyć się z podlinkowanym na ścieżce wykrywania, wykonując żądanie HTTP PROPFIND na:

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

Po przekierowaniu (HTTP 301) do zasobu książki adresowej, Twój program dla klientów może wykonać na nim PROPFIND, by wykryć DAV:current-user-principal, DAV:principal-URL i addressbook-home-set usług. Dzięki temu program Twoich klientów może odkryć główną książkę adresową, wykonując PROPFIND na urządzeniu addressbook-home-set i szukając addressbook i collection zasoby. Pełny opis tego procesu wykracza poza zakres tego dokumentu. Zobacz rfc6352, aby dowiedzieć się więcej.

Ścieżka przekierowania zwrócona w odpowiedzi HTTP 301 przez PROPFIND dobrze znany identyfikator URI nie może być trwale przechowywany w pamięci podręcznej (zgodnie z rfc6764). Urządzenia powinny ponawiać próbę połączenia ze znanymi danymi okresowe wykrywanie identyfikatorów URI w celu sprawdzania, czy ścieżka w pamięci podręcznej jest nadal aktualna; ponownie zsynchronizować, jeśli ścieżka kiedykolwiek się zmieni. Zalecamy częstotliwość wyświetlania reklam co 2–4 tygodnie.

Zasoby

CardDAV korzysta z koncepcji REST. Aplikacje klienckie działają na zasobach, które są wyznaczone przez ich identyfikatory URI. W tym miejscu podano bieżącą strukturę identyfikatora URI, aby ułatwić rozumieją pojęcia podane w tej sekcji. Obiekt może nie może być zakodowana na stałe. Zasoby powinny być raczej wykrywane zgodnie z 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 znajduje się ogólny opis obsługiwanych operacji. Programiści powinien sprawdzić szczegóły w odpowiednim dokumencie RFC. Prośby i odpowiedzi są głównie zakodowane w formacie XML. To są główne operacje używane przez klienta aplikacje do synchronizacji:

• Korzystanie z tagu CTag
  • Programy klientów używają żądania getctag PROPFIND z książki adresowej w celu określenia, czy którykolwiek kontakt na serwerze uległ zmianie oraz co pozwala określić, czy synchronizacja jest potrzebna. Wartość tej właściwości na pewno ulec zmianie w przypadku zmiany danych kontaktowych. Aplikacje klienckie powinien zapisywać tę wartość i używać jej tylko przy pierwszej synchronizacji oraz w przypadku, gdy wartość sync-token jest unieważniona. Okresowe odpytywanie Właściwość getctag spowoduje ograniczenie.
• Używanie tokena synchronizacji
  • Programy klienckie używają żądania sync-token PROPFIND z adresem Książka, by uzyskać obiekt sync-token reprezentujący jego bieżący stan. Klient aplikacje muszą przechowywać tę wartość i okresowo wydawać sync-collection REPORT prośby o określenie zmian od ostatniego wysłania sync-token Wydane tokeny są ważne przez 29 dni, a REPORT odpowiedź będzie zawierać nowy element sync-token.
• Używanie ETagów
  • Aplikacje klienckie wysyłają żądanie getetag PROPFIND dotyczące adresu Zasób książki (z nagłówkiem DEPTH równym DEPTH_1). Poprzez utrzymanie wartość ETag każdego kontaktu, program klienta może zażądać tej wartości z kontaktów, których wartość typu ETag została zmieniona.
• Pobieram kontakty
  • Aplikacje klienckie pobierają kontakty przez wysłanie addressbook-multiget prośba o: REPORT. Na podstawie listy identyfikatorów URI kontaktów raport zwróci wszystkie żądane kontakty jako wartości VCard 3.0. Każdy wpis zawiera znak ETag dla kontaktu.
• Wstawianie kontaktu
  • Aplikacje klienckie wysyłają żądanie POST z nowym kontaktem w VCard Format 3.0. Odpowiedź będzie zawierać identyfikator nowego kontaktu.
• Aktualizowanie kontaktu
  • Aplikacje klienckie wysyłają żądanie PUT do zaktualizowanej osoby kontaktowej w: Format VCard 3.0. Jeśli kontakt już istnieje, zostanie zaktualizowany w książce adresowej.
  • Aplikacje klienckie powinny zawierać nagłówek If-Match ze znakiem kontakt jest obecnie znany: ETag. Serwer odrzuci wtedy PUT. (z HTTP 412), jeśli bieżący ETag na serwerze jest różni się od ETag wysłanego przez program kliencki. Dzięki temu optymistycznej serializacji aktualizacji.
• Usuwanie kontaktu
  • Aplikacje klienckie usuwają kontakt, wysyłając żądanie DELETE do identyfikatora URI kontaktu.