إدارة جهات الاتصال باستخدام بروتوكول CardDAV
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يمكنك عرض جهات الاتصال وإدارتها باستخدام بروتوكول CardDAV من Google.
يتم تخزين جهات الاتصال في حساب المستخدم على Google. تتميز معظم خدمات Google
الوصول إلى قائمة جهات الاتصال. يمكن لتطبيق العميل استخدام واجهة برمجة التطبيقات CardDAV من أجل
إنشاء جهات اتصال جديدة، وتعديل جهات الاتصال الحالية أو حذفها، وطلب البحث عن جهات الاتصال
التي تطابق معايير معينة.
المواصفات
لم يتم تنفيذ المواصفات الكاملة، ولكن العديد من العملاء مثل
جهات اتصال Apple iOSTM
وأن يعمل نظام التشغيل macOS بشكل صحيح.
لكل مواصفات ذات صلة، يتم دعم CardDAV من Google على النحو التالي:
يتطلب بروتوكول CardDAV من Google استخدام بروتوكول OAuth 2.0.
تتطلّب واجهة CardDAV من Google توفّر OAuth 2.0. يمكنك الرجوع إلى الوثائق المُدرَجة أدناه للحصول على معلومات عن استخدام OAuth 2.0 للوصول إلى Google APIs:
الاتصال بخادم CardDAV من Google
يسمح بروتوكول CardDAV باكتشاف دفتر العناوين وموارد جهات الاتصال
معرّفات الموارد المنتظمة (URI). يجب عدم إجراء ترميز ثابت لأي عنوان URI، إذ يمكن أن يتغير في أي وقت.
يجب أن تستخدم تطبيقات العميل بروتوكول HTTPS، ويجب أن يتم توفير مصادقة OAuth 2.0
لحساب المستخدم على Google. لن يمحو خادم CardDAV مصادقة أي طلب ما لم يصل عبر بروتوكول HTTPS باستخدام مصادقة OAuth 2.0 لحساب Google، ويكون تطبيقك مسجَّلاً على DevConsole. أي محاولة للاتصال عبر HTTP باستخدام المصادقة الأساسية أو باستخدام
يؤدي عنوان البريد الإلكتروني/كلمة المرور التي لا تتطابق مع حساب Google إلى HTTP
رمز الاستجابة 401 Unauthorized
لاستخدام CardDAV، يجب أن يتصل برنامج العميل في البداية بموقعك الإلكتروني.
مسار استكشاف المحتوى من خلال تنفيذ PROPFIND HTTP على:
https://www.googleapis.com/.well-known/carddav
بعد إعادة توجيهك (HTTP 301) إلى مورد دفتر العناوين، سيستخدم برنامج العميل
يمكننا بعد ذلك تنفيذ PROPFIND عليه لاكتشاف
DAV:current-user-principal وDAV:principal-URL وaddressbook-home-set
المواقع. ويمكن لبرنامج العميل عندئذٍ اكتشاف دفتر العناوين الرئيسي من خلال
إجراء PROPFIND على addressbook-home-set والبحث عن
المرجع addressbook وcollection وصف كامل لهذه العملية
ليس نطاق هذه الوثيقة. عرض
rfc6352 لمزيد من التفاصيل.
يجب عدم تخزين مسار إعادة التوجيه الذي تم إرجاعه في استجابة HTTP 301 من خلال PROPFIND على
معرّف الموارد المنتظم (URI) المعروف بشكل دائم (وفقًا
rfc6764). على الأجهزة إعادة محاولة اكتشاف عناوين URI المعروفة بشكل دوري للتحقّق مما إذا كان المسار المخزّن مؤقتًا لا يزال محدّثًا، ومحاولة تتميم عملية الربط مجددًا في حال تغيّر المسار. تنصح Google بتحديد سعر كل أسبوعَين إلى 4 أسابيع.
الموارد
يستخدم CardDAV مفاهيم REST. تعمل تطبيقات العميل على الموارد التي يتم تحديدها من خلال عناوين URL الخاصة بها. تم تحديد بنية عنوان URL الحالية هنا لمساعدة المطوّرين في فهم المفاهيم الواردة في القسم التالي. قد تتغيّر البنية، ويجب ألّا تكون برمجية. بدلاً من ذلك، يجب اكتشاف الموارد
وفقًا لـ RFC.
- مدير المدرسة
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- الطقم المنزلي
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists
- دفتر العناوين
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default
- التواصل
- https://www.googleapis.com/carddav/v1/principals/
userEmail/lists/default/contactId
في ما يلي وصف عام للعمليات المتوافقة. المطوّرون
يجب أن يبحث عن التفاصيل في RFC ذي الصلة. تُعد الطلبات والردود
بترميز XML في الغالب. هذه هي العمليات الرئيسية التي يستخدمها العميل
تطبيقات للمزامنة:
- استخدام CTag
- تستخدم برامج العملاء طلب
getctag PROPFIND في دفتر العناوين
لتحديد ما إذا كانت أي جهة اتصال قد تغيرت على الخادم
وبالتالي ما إذا كانت هناك حاجة إلى المزامنة. قيمة هذا الموقع
مضمون للتغيير إذا تم تغيير أي جهة اتصال. على تطبيقات العميل
تخزين هذه القيمة واستخدامها فقط في المزامنة الأولية وكملاذ sync-token عند إلغاء صلاحيتها. سيؤدي إجراء استطلاع دوري في
ستؤدي السمة getctag إلى تقييد البيانات.
- استخدام الرمز المميّز للمزامنة
- تستخدم برامج العملاء طلب
sync-token PROPFIND في "العنوان"
احجز للحصول على sync-token الذي يمثل حالته الحالية. يجب أن تخزِّن تطبيقات العميل
هذه القيمة وتُصدر طلبات sync-collection
REPORT دورية لتحديد التغييرات منذ آخر
sync-token تم إصداره. تكون الرموز المميّزة الصادرة صالحة لمدة 29 يومًا، وREPORT
سيحتوي الرد على sync-token جديد.
- استخدام علامات ETag
- تُصدر تطبيقات العميل طلب
getetag PROPFIND على مورد "دفتر عناوين" (مع عنوان DEPTH يساوي DEPTH_1). من خلال الاحتفاظ
بقيمة ETag لكل جهة اتصال، يمكن لبرنامج العميل طلب قيمة
جهات الاتصال التي تم تغيير ETag فيها.
- استرداد جهات الاتصال
- تسترد تطبيقات العميل جهات الاتصال من خلال إصدار
طلب "
addressbook-multiget" للحصول على REPORT بالنظر إلى قائمة من معرفات الموارد المنتظمة (URI) لجهة الاتصال،
سيعرض التقرير جميع جهات الاتصال المطلوبة كقيم VCard 3.0. يحتوي كل
إدخال على ETag لجهة الاتصال.
- إدراج جهة اتصال
- تصدر تطبيقات العميل طلب
POST مع جهة الاتصال الجديدة في VCard
3.0. سيحتوي الردّ على رقم تعريف جهة الاتصال الجديدة.
- تعديل جهة اتصال
- تُصدر تطبيقات العميل طلب
PUT يتضمّن جهة الاتصال المعدّلة بتنسيق
VCard 3.0. يتم تعديل جهة الاتصال إذا كانت موجودة
في دفتر العناوين.
- يجب أن تحتوي تطبيقات العملاء على العنوان
If-Match مع
جهة الاتصال المعروفة حاليًا ETag. سيرفض الخادم بعد ذلك طلب PUT
(مع HTTP 412) إذا كان ETag الحالي على الخادم مختلفًا عنETag الذي أرسله برنامج العميل. هذا يسمح
التسلسل المتفائل للتحديثات.
- حذف جهة اتصال
- تحذف تطبيقات العملاء جهة اتصال من خلال إصدار طلب
DELETE.
مقابل عنوان URI لجهة الاتصال.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
