Kişileri CardDAV protokolüyle yönetme
Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Kişilerinizi Google'ın CardDAV protokolünü kullanarak görüntüleyebilir ve yönetebilirsiniz.
Kişiler kullanıcının Google Hesabında saklanır; çoğu Google hizmetinde
kişi listesine erişebilir. İstemci uygulamanız CardDAV API'yi kullanarak
yeni kişi oluşturma, mevcut kişileri düzenleme veya silme ve kişileri sorgulama
reklam grubu da oluşturabilirsiniz.
Özellikler
Tam spesifikasyon uygulanmadı, ancak
Apple iOSTM Kişiler
ve macOS'in doğru şekilde birlikte çalışması gerekir.
İlgili her spesifikasyon için Google'ın CardDAV desteği aşağıdaki gibidir:
- rfc2518: Distributed Authoring için HTTP Uzantıları (WebDAV)
GET, PUT, DELETE, OPTIONS ve PROPFIND HTTP yöntemlerini destekler.LOCK, UNLOCK, COPY, MOVE veya MKCOL HTTP yöntemlerini desteklemez.- İsteğe bağlı (kullanıcı tanımlı) WebDAV özelliklerini desteklemez.
- WebDAV Erişim Denetimi'ni desteklemez (rfc3744).
- rfc5995: WebDAV Koleksiyonlarına Üye Eklemek İçin POST'u Kullanma
- Bir kimlik belirtmeden yeni kişiler oluşturmayı destekler.
- rfc6352: CardDAV: vCard Uzantıları, Web'de Dağıtılmış Yazma ve
Sürüm oluşturma (WebDAV)
REPORT HTTP yöntemini destekler ancak tanımlanan tüm raporlar uygulanmaz.- Ana koleksiyon ve kişi koleksiyonu sağlama özelliğini destekler.
- rfc6578: WebDAV için Koleksiyon Senkronizasyonu
- rfc6749: OAuth 2.0 Yetkilendirme Çerçevesi ve
rfc6750: OAuth 2.0 Yetkilendirme Çerçevesi: Taşıyıcı Jeton Kullanımı
- CardDAV istemci programlarının kimliğinin OAuth 2.0 HTTP kullanılarak doğrulanmasını destekler
Kimlik doğrulama. Google başka hiçbir kimlik doğrulama yöntemini desteklemez.
Kişi verilerinin güvenliği için CardDAV bağlantılarının HTTPS kullanması gerekir.
- rfc6764: WebDAV'deki Takvim Uzantıları (CalDAV) ve WebDAV'deki vCard Uzantıları (CardDAV) için Hizmetleri Bulun
- CardDAV URL'lerinin önyüklemesi, rfc6764'ün 6. bölümüne göre yapılmalıdır.
- Destekler
caldav-ctag-02: CalDAV'daki Takvim Koleksiyonu Varlık Etiketi (CTag),
Bu bağlantı, CardDAV ve CalDAV özellikleri arasında paylaşılır. Kişiler
ctag, bir kaynak ETag gibidir. Kişi adres defterinde herhangi bir değişiklik olduğunda değişir. Böylece, istemci programı,
senkronize edilmesi gerekmez.
- Google, kişi kodlama biçimi olarak VCard 3.0'ı kullanır. Bkz.:
rfc6350: VCard 3.0.
Google'ın CardDAV'ı için OAuth 2.0 gerekir
Google'ın CardDAV arayüzü için OAuth 2.0 gereklidir. Bağlantılı
şu dokümanları inceleyin:
Google'ın CardDAV sunucusuna bağlanma
CardDAV protokolü, adres defteri ve kişi kaynaklarının URI'lerinin keşfedilmesine olanak tanır. Her an değişebileceği için hiçbir URI'nın kodunu gömmemeniz gerekir.
İstemci uygulamaları HTTPS kullanmalı ve OAuth 2.0 kimlik doğrulaması,
(kullanıcının Google hesabı için) CardDAV sunucusu
bir istek OAuth 2.0 ile HTTPS üzerinden ulaşmadıkça kimliğini doğrulama
bir Google Hesabı'nın kimlik doğrulamasından yararlanabiliyorsanız ve uygulamanız
DevConsole. Temel kimlik doğrulaması veya
bir Google hesabıyla eşleşmeyen bir e-posta/şifre, HTTP ile sonuçlanıyorsa
401 Unauthorized yanıt kodu.
CardDAV'ı kullanmak için istemci programınızın ilk olarak standart sayfaya bağlanması gerekir
şurada bir HTTP PROPFIND gerçekleştirerek keşif yolu:
https://www.googleapis.com/.well-known/carddav
Bir Adres Defteri Kaynağına (HTTP 301) yönlendirildikten sonra istemci programınız
daha sonra,PROPFIND
DAV:current-user-principal, DAV:principal-URL ve addressbook-home-set
özellikler. Böylece istemci programınız ana adres defterini
addressbook-home-set cihazında PROPFIND gerçekleştiriyor ve
addressbook ve collection kaynakları. Bu sürecin tam açıklaması bu dokümanın kapsamı dışındadır. Daha fazla bilgi için rfc6352 sayfasına bakın.
Şu tarihte bir PROPFIND aracılığıyla HTTP 301 yanıtında döndürülen yönlendirme yolu:
iyi bilinen URI kalıcı olarak önbelleğe alınmamalıdır (
rfc6764). Cihazlar, önbelleğe alınan yolun hâlâ güncel olup olmadığını doğrulamak ve yol değişirse yeniden senkronize etmek için bilinen URI keşfini düzenli aralıklarla yeniden denemelidir. Google, 2-4 haftada bir gönderim yapmanızı önerir.
Kaynaklar
CardDAV, REST kavramlarını kullanır. İstemci uygulamaları, URI'leri ile tanımlanan kaynaklar üzerinde işlem yapar. Yardımcı olması için geçerli URI yapısı burada belirtilmiştir
geliştiriciler aşağıdaki bölümde yer alan kavramları anlamıştır. Yapı değişebilir ve sabit kodla yazılmamalıdır. Bunun yerine, kaynaklar RFC'ye göre bulunmalıdır.
- Müdür
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- Ev Ayarlama
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- Adres Defteri
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- İletişim
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
Aşağıda, desteklenen işlemlerin genel bir açıklaması yer almaktadır. Geliştiriciler, ilgili RFC'de ayrıntıları bulabilir. İstekler ve yanıtlar
XML'de kodlanır. Bunlar, istemci tarafından kullanılan ana işlemlerdir.
senkronizasyon uygulamaları:
- CTag'i kullanma
- İstemci programları, Adres Defteri'nde
getctag PROPFIND isteğini kullanır
ve herhangi bir kişinin sunucuda değişip değişmediğini belirlemek için bir
bu nedenle senkronizasyon gerekip gerekmediği. Herhangi bir kişi değişirse bu mülkün değerinin değişeceği garanti edilir. İstemci uygulamaları bu değeri depolamalı ve yalnızca ilk senkronizasyonda ve bir sync-token geçersiz olduğunda yedek olarak kullanmalıdır. getctag mülkü için düzenli olarak yoklama yapılması, mülkün sınırlandırılmasına neden olur.
- sync-token parametresini kullanma
- İstemci programları, mevcut durumunu temsil eden
sync-token öğesini almak için Adres Defteri'ndeki sync-token PROPFIND isteğini kullanır. Müşteri
uygulamalar bu değeri depolamalı ve düzenli olarak sync-collection vermelidir.
Son gönderilen tarihten bu yana yapılan değişiklikleri belirlemek için REPORT istek gönderildi
sync-token. Verilen jetonlar 29 gün boyunca geçerlidir ve REPORT
yanıt yeni bir sync-token içerecek.
- E-etiketleri kullanma
- İstemci uygulamaları, Adres Defteri kaynağında (
DEPTH başlığı DEPTH_1'a eşit olacak şekilde) bir getetag PROPFIND isteği gönderir. İstemci programı, her kişinin ETag değerini koruyarak ETag değeri değiştirilen kişilerin değerini isteyebilir.
- Kişileri getirme
- İstemci uygulamaları, kişileri bir
addressbook-multiget REPORT isteği. Rapor, iletişim URI'lerinin bir listesini aldığında istenen tüm kişileri VCard 3.0 değerleri olarak döndürür. Her girişte kişi için bir ETag bulunur.
- Kişi ekleme
- İstemci uygulamaları, VCard'daki yeni kişiye bir
POST isteği gönderir.
3.0 biçiminde indirilmelidir. Yanıtta yeni kişinin kimliği yer alır.
- Kişileri güncelleme
- İstemci uygulamaları, güncellenmiş kişiyi VCard 3.0 biçiminde içeren bir
PUT isteği gönderir. Kişi zaten mevcutsa güncellenir
yazın.
- İstemci uygulamaları,
If-Match
kişinin şu anda bilinen ETag. Sunucudaki mevcut ETag, istemci programı tarafından gönderilen ETag'den farklıysa sunucu PUTisteğini (HTTP 412 ile) reddeder. Bu, güncellemelerin iyimser bir şekilde serileştirilmesine olanak tanır.
- Kişiyi silme
- Müşteri uygulamaları, kişi URI'sine karşı bir
DELETE isteği göndererek kişiyi siler.
Aksi belirtilmediği sürece bu sayfanın içeriği Creative Commons Atıf 4.0 Lisansı altında ve kod örnekleri Apache 2.0 Lisansı altında lisanslanmıştır. Ayrıntılı bilgi için Google Developers Site Politikaları'na göz atın. Java, Oracle ve/veya satış ortaklarının tescilli ticari markasıdır.
Son güncelleme tarihi: 2025-07-25 UTC.
[[["Anlaması kolay","easyToUnderstand","thumb-up"],["Sorunumu çözdü","solvedMyProblem","thumb-up"],["Diğer","otherUp","thumb-up"]],[["İhtiyacım olan bilgiler yok","missingTheInformationINeed","thumb-down"],["Çok karmaşık / çok fazla adım var","tooComplicatedTooManySteps","thumb-down"],["Güncel değil","outOfDate","thumb-down"],["Çeviri sorunu","translationIssue","thumb-down"],["Örnek veya kod sorunu","samplesCodeIssue","thumb-down"],["Diğer","otherDown","thumb-down"]],["Son güncelleme tarihi: 2025-07-25 UTC."],[[["\u003cp\u003eGoogle Contacts can be accessed and managed using the CardDAV protocol, enabling client applications to create, edit, delete, and query contacts.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV implementation requires OAuth 2.0 for authentication and HTTPS for secure connections.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should discover resource URIs dynamically instead of hardcoding them, as they are subject to change.\u003c/p\u003e\n"],["\u003cp\u003eContact synchronization can be achieved using CTag, sync-token, or ETags to efficiently track and update changes.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's CardDAV utilizes VCard 3.0 for encoding contact data.\u003c/p\u003e\n"]]],["Google's CardDAV protocol allows managing contacts stored in a Google Account. Client applications can create, edit, delete, and query contacts using the CardDAV API. Key actions include using `PROPFIND` for discovery and obtaining `sync-token` and `getctag` for synchronization. Retrieving contacts is done with `addressbook-multiget REPORT`, while inserting, updating, and deleting contacts utilize `POST`, `PUT` (with `If-Match`), and `DELETE` requests, respectively. Authentication requires HTTPS and OAuth 2.0, and VCard 3.0 is the contact encoding format.\n"],null,["# Manage contacts with the CardDAV protocol\n\nYou can view and manage your contacts using Google's CardDAV protocol.\n\nContacts are stored in the user's Google Account; most Google services have\naccess to the contact list. Your client application can use the CardDAV API to\ncreate new contacts, edit or delete existing contacts, and query for contacts\nthat match particular criteria.\n\nSpecifications\n--------------\n\nThe full specification is not implemented, but many clients such as\n[Apple iOS™ Contacts](https://support.google.com/contacts/answer/2753077?co=GENIE.Platform%3DiOS)\nand macOS should interoperate correctly.\n\nFor each relevant specification, Google's CardDAV support is as follows:\n\n- [rfc2518: HTTP Extensions for Distributed Authoring (WebDAV)](https://tools.ietf.org/html/rfc2518)\n - Supports the HTTP methods `GET`, `PUT`, `DELETE`, `OPTIONS`, and `PROPFIND`.\n - Does *not* support the HTTP methods `LOCK`, `UNLOCK`, `COPY`, `MOVE`, or `MKCOL`.\n - Does *not* support arbitrary (user-defined) WebDAV properties.\n - Does *not* support WebDAV Access Control (rfc3744).\n- [rfc5995: Using POST to Add Members to WebDAV Collections](https://tools.ietf.org/html/rfc5995)\n - Supports creating new contacts without specifying an ID.\n- [rfc6352: CardDAV: vCard Extensions to Web Distributed Authoring and\n Versioning (WebDAV)](https://tools.ietf.org/html/rfc6352)\n - Supports the HTTP method `REPORT`, but not all defined reports are implemented.\n - Supports providing a principal collection and a contacts collection.\n- [rfc6578: Collection Synchronization for WebDAV](https://tools.ietf.org/html/rfc6578)\n - Client applications must switch to this mode of operation after the initial sync.\n- [rfc6749: The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) and [rfc6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)\n - Supports authenticating CardDAV client programs using OAuth 2.0 HTTP Authentication. Google does not support any other authentication method. For security of contact data, we require CardDAV connections to use [HTTPS](https://en.wikipedia.org/wiki/HTTPS).\n- [rfc6764: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)](https://tools.ietf.org/html/rfc6764)\n - Bootstrapping of CardDAV URLs must take place according to section 6 of rfc6764.\n- Supports [caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV](https://github.com/apple/ccs-calendarserver/blob/master/doc/Extensions/caldav-ctag.txt), which is shared between the CardDAV and CalDAV specifications. The contacts `ctag` is like a resource `ETag`; it changes when anything in the contact address book has changed. This allows the client program to quickly determine that it does not need to synchronize any changed contacts.\n- Google uses VCard 3.0 as the contact encoding format. See: [rfc6350: VCard 3.0](https://tools.ietf.org/html/rfc6350).\n\nGoogle's CardDAV requires OAuth 2.0\n-----------------------------------\n\nGoogle's CardDAV interface requires OAuth 2.0. Refer to the linked\ndocumentation below for information on using OAuth 2.0 to access Google APIs:\n\n- [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)\n- [Using OAuth 2.0 for Installed Applications](https://developers.google.com/identity/protocols/oauth2/native-app)\n\nConnecting to Google's CardDAV server\n-------------------------------------\n\nThe CardDAV protocol allows discovery of the address book and contact resources\nURIs. You must not hardcode any URI as they could change at any time.\n\nClient applications must use HTTPS, and `OAuth 2.0` authentication must be\nprovided for the user's Google account. The CardDAV server will not\nauthenticate a request unless it arrives over HTTPS with OAuth 2.0\nauthentication of a Google account, and your application is registered on\nDevConsole. Any attempt to connect over HTTP with Basic authentication or with\nan email/password that doesn't match a Google account results in an HTTP\n`401 Unauthorized` response code.\n\nTo use CardDAV, your client program must initially connect to the canonical\ndiscovery path by performing an HTTP `PROPFIND` on: \n\n https://www.googleapis.com/.well-known/carddav\n\nOnce redirected (`HTTP 301`) to an Address Book Resource, your client program\ncan then perform a `PROPFIND` on it to discover the\n`DAV:current-user-principal`, `DAV:principal-URL`, and `addressbook-home-set`\nproperties. Your client program can then discover the principal address book by\nperforming a `PROPFIND` on the `addressbook-home-set` and looking for the\n`addressbook` and `collection` resources. A full description of this process\nis beyond the scope of this document. See\n[rfc6352](https://tools.ietf.org/html/rfc6352) for more details.\n\nThe redirect path returned in the `HTTP 301` response through a `PROPFIND` on\nthe well-known URI must **not** be permanently cached (as per\n[rfc6764](https://tools.ietf.org/html/rfc6764)). Devices should retry well-known\nURI discovery periodically to verify if the cached path is still up to date and\nresync if the path ever changes. Google recommends a rate of every 2-4 weeks.\n\nResources\n---------\n\nCardDAV uses REST concepts. Client applications act on resources that are\ndesignated by their URIs. The current URI structure is specified here to help\ndevelopers understand the concepts in the following section. The structure may\nchange and must not be hardcoded. Rather, the resources should be discovered\naccording to the RFC.\n\n1. **Principal**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e\n2. **Home Set**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists\n3. **Address Book**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default\n4. **Contact**\n - https://www.googleapis.com/carddav/v1/principals/\u003cvar class=\"apiparam\" translate=\"no\"\u003euserEmail\u003c/var\u003e/lists/default/\u003cvar class=\"apiparam\" translate=\"no\"\u003econtactId\u003c/var\u003e\n\nSynchronizing Contacts\n----------------------\n\nThe following is a general description of the operations supported. Developers\nshould look for the details in the relevant RFC. Requests and responses are\nmostly encoded in XML. These are the main operations used by client\napplications for synchronization:\n\n- **Using CTag**\n - Client programs use the `getctag` `PROPFIND` request on the Address Book resource to determine if any contact has changed on the server and therefore whether a synchronization is needed. The value of this property is guaranteed to change if any contact changes. Client applications should store this value and use it only on the initial sync and as a fallback when a `sync-token` is invalidated. Periodically polling for the `getctag` property will result in throttling.\n- **Using sync-token**\n - Client programs use the `sync-token` `PROPFIND` request on the Address Book to obtain the `sync-token` representing its current state. Client applications must store this value and issue periodic `sync-collection` `REPORT` requests to determine changes since the last issued `sync-token`. Issued tokens are valid for 29 days, and the `REPORT` response will contain a new `sync-token`.\n- **Using ETags**\n - Client applications issue a `getetag` `PROPFIND` request on the Address Book resource (with `DEPTH` header equal to `DEPTH_1`). By maintaining the `ETag` value of each contact, a client program can request the value of contacts that had their `ETag` changed.\n- **Retrieving contacts**\n - Client applications retrieve contacts by issuing an `addressbook-multiget` `REPORT` request. Given a list of contact URIs, the report returns all the requested contacts as VCard 3.0 values. Each entry includes an `ETag` for the contact.\n- **Inserting a contact**\n - Client applications issue a `POST` request with the new contact in VCard 3.0 format. The response will contain the ID of the new contact.\n- **Updating a contact**\n - Client applications issue a `PUT` request with the updated contact in VCard 3.0 format. The contact is updated if the contact already exists in the address book.\n - Client applications should include an `If-Match` header with the contact's currently known `ETag`. The server will then reject the `PUT` request (with `HTTP 412`) if the current `ETag` on the server is different from the `ETag` sent by the client program. This allows for optimistic serialization of updates.\n- **Deleting a contact**\n - Client applications delete a contact by issuing a `DELETE` request against the contact URI."]]
