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
iPROPFIND
. - Nie obsługuje metod HTTP
LOCK
,UNLOCK
,COPY
,MOVE
aniMKCOL
. - Nie obsługuje dowolnych (zdefiniowanych przez użytkownika) właściwości WebDAV.
- Nie obsługuje kontroli dostępu WebDAV (rfc3744).
- Obsługuje metody HTTP
- 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.
- Obsługuje metodę HTTP
- 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óbETag
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.
- Podmiot zabezpieczeń
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- Zestaw domowy
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- Książka adresowa
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- Kontakt
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
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, gdysync-token
zostanie unieważniony. Okresowe odpytywanie właściwościgetctag
spowoduje ograniczanie.
- Programy klienckie używają żądania
- Używanie tokena synchronizacji
- Programy klienta korzystają z żądania
sync-token
PROPFIND
w książce adresowej, aby uzyskać parametrsync-token
wskazujący jego bieżący stan. Aplikacje klienckie muszą przechowywać tę wartość i wysyłać okresowe żądaniasync-collection
REPORT
, aby określić zmiany od ostatniego wydaniasync-token
. Wydane tokeny są ważne przez 29 dni, a odpowiedźREPORT
będzie zawierać nową wartośćsync-token
.
- Programy klienta korzystają z żądania
- Używanie tagów ETag
- Aplikacje klienckie wysyłają żądanie
getetag
PROPFIND
do zasobu książki adresowej (z nagłówkiemDEPTH
równymDEPTH_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.
- Aplikacje klienckie wysyłają żądanie
- 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 zawieraETag
odpowiedniego kontaktu.
- Aplikacje klienckie pobierają kontakty, wysyłając żądanie
- Wstawianie kontaktu
- Aplikacje klienckie wysyłają żądanie
POST
do nowego kontaktu w formacie VCard 3.0. Odpowiedź będzie zawierać identyfikator nowego kontaktu.
- Aplikacje klienckie wysyłają żądanie
- 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 identyfikatoremETag
kontaktu. Serwer odrzuci wtedy żądaniePUT
(zHTTP 412
), jeśli bieżąca wartośćETag
na serwerze różni się od żądaniaETag
wysłanego przez program klienta. Pozwala to zoptymalizować serializację aktualizacji.
- Aplikacje klienckie wysyłają żądanie
- Usuwanie kontaktu
- Aplikacje klienckie usuwają kontakt, wysyłając żądanie
DELETE
zamiast identyfikatora URI kontaktu.
- Aplikacje klienckie usuwają kontakt, wysyłając żądanie