Zarządzanie kontaktami za pomocą protokołu CardDAV

Kontakty możesz wyświetlać i nimi zarządzać za pomocą protokołu CardDAV Google.

Kontakty są przechowywane na koncie Google użytkownika. Większość usług Google ma dostęp do listy kontaktów. Za pomocą interfejsu CardDAV API aplikacja klienta może tworzyć nowe kontakty, edytować i usuwać istniejące kontakty oraz wysyłać zapytania o kontakty spełniające 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 specyfikacji Google obsługuje CardDAV w następujący sposób:

Protokół CardDAV Google wymaga protokołu OAuth 2.0

Interfejs Google CardDAV wymaga protokołu OAuth 2.0. Informacje o używaniu protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google znajdziesz w poniżej wymienionej dokumentacji:

Łączenie z serwerem CardDAV Google

Protokół CardDAV umożliwia wykrywanie książki adresowej i zasobów kontaktów (URI). Nie należy kodować na stałe żadnych identyfikatorów URI, 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 uwierzytelnia żądania, chyba że zostało ono przesłane przez HTTPS z użyciem uwierzytelniania OAuth 2.0 na koncie Google, a Twoja aplikacja jest zarejestrowana w DevConsole. Każda próba nawiązania połączenia przez HTTP z użyciem uwierzytelniania podstawowego lub z adresem e-mail i hasłem, które nie pasują do konta Google, powoduje otrzymanie kodu odpowiedzi HTTP 401 Unauthorized.

Aby korzystać z CardDAV, program klienta musi najpierw połączyć się z kanoniczną ścieżką wykrywania, wykonując operację HTTP PROPFIND na:

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

Po przekierowaniu (HTTP 301) do zasobu książki adresowej program klienta może wykonać na nim operację PROPFIND, aby poznać właściwości DAV:current-user-principal, DAV:principal-URL i addressbook-home-set. Program klienta może następnie znaleźć główną książkę adresową, wykonując operację PROPFIND w addressbook-home-set i szukając zasobów addressbook i collection. 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. Google zaleca, aby robić to co 2–4 tygodnie.

Zasoby

CardDAV korzysta z koncepcji REST. Aplikacje klienckie działają na zasobach, które są wyznaczone przez ich identyfikatory URI. Aby pomóc deweloperom zrozumieć pojęcia opisane w następnej sekcji, podajemy tutaj obecną strukturę URI. Obiekt może 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 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

Synchronizacja kontaktów

Poniżej znajdziesz ogólny opis obsługiwanych operacji. Deweloperzy powinni szukać szczegółów w odpowiednich dokumentach RFC. Prośby i odpowiedzi są głównie zakodowany w formacie XML. Oto główne operacje używane przez aplikacje klienckie do synchronizacji:

  • Korzystanie z 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 powinny przechowywać tę wartość i używać jej tylko podczas początkowej synchronizacji oraz jako wartości zastępczej, gdy sync-token zostanie unieważniony. Okresowe odpytywanie Właściwość getctag spowoduje ograniczenie.
  • Korzystanie z 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. Aplikacje klienta muszą przechowywać tę wartość i wysyłać okresowo żądania sync-collectionREPORT, aby określić zmiany od ostatniego wysłania sync-token. Wydane tokeny są ważne przez 29 dni, a odpowiedź REPORT będzie zawierać nowy token sync-token.
  • Używanie ETagów
    • Aplikacje klienckie wysyłają getetag PROPFIND do zasobu książki adresowej (z nagłówkiem DEPTH równym DEPTH_1). Dzięki temu, że program klienta zachowuje wartość ETag każdego kontaktu, może on poprosić o wartość kontaktów, których wartość ETag uległa zmianie.
  • Pobieranie kontaktów
    • 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żda pozycja zawiera ETag kontaktu.
  • Wstawianie kontaktu
    • Aplikacje klienckie wysyłają żądanie POST z nowym kontaktem w formacie vCard 3.0. Odpowiedź będzie zawierać identyfikator nowego kontaktu.
  • Aktualizowanie kontaktu
    • Aplikacje klienckie wysyłają żądanie PUT z aktualnymi danymi kontaktowymi w formacie VCard 3.0. Jeśli kontakt już istnieje, zostanie zaktualizowany w książce adresowej.
    • W zapytaniach klienta powinien znajdować się nagłówek If-Match z aktualnym ETag kontaktu. 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 DELETE do URI kontaktu.