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
iPROPFIND
. - Nie obsługuje metod HTTP
LOCK
,UNLOCK
,COPY
,MOVE
aniMKCOL
- Dowolne (zdefiniowane przez użytkownika) właściwości WebDAV nie są obsługiwane.
- Nie obsługuje kontroli dostępu WebDAV (rfc3744).
- Obsługuje metody HTTP
- 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.
- Obsługuje metodę HTTP
- 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óbETag
; 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.
- 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 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.
- Programy klientów używają żądania
- Używanie tokena synchronizacji
- Programy klienckie używają żądania
sync-token
PROPFIND
z adresem Książka, by uzyskać obiektsync-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łaniasync-token
Wydane tokeny są ważne przez 29 dni, aREPORT
odpowiedź będzie zawierać nowy elementsync-token
.
- Programy klienckie używają żądania
- Używanie ETagów
- Aplikacje klienckie wysyłają żądanie
getetag
PROPFIND
dotyczące adresu Zasób książki (z nagłówkiemDEPTH
równymDEPTH_1
). Poprzez utrzymanie wartośćETag
każdego kontaktu, program klienta może zażądać tej wartości z kontaktów, których wartość typuETag
została zmieniona.
- Aplikacje klienckie wysyłają żądanie
- 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 znakETag
dla kontaktu.
- Aplikacje klienckie pobierają kontakty przez wysłanie
- Wstawianie kontaktu
- Aplikacje klienckie wysyłają żądanie
POST
z nowym kontaktem w VCard Format 3.0. Odpowiedź będzie zawierać identyfikator nowego kontaktu.
- Aplikacje klienckie wysyłają żądanie
- 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 wtedyPUT
. (zHTTP 412
), jeśli bieżącyETag
na serwerze jest różni się odETag
wysłanego przez program kliencki. Dzięki temu optymistycznej serializacji aktualizacji.
- Aplikacje klienckie wysyłają żądanie
- Usuwanie kontaktu
- Aplikacje klienckie usuwają kontakt, wysyłając żądanie
DELETE
do identyfikatora URI kontaktu.
- Aplikacje klienckie usuwają kontakt, wysyłając żądanie