يمكنك عرض جهات اتصالك وإدارتها باستخدام بروتوكول CardDAV من Google.
يتم تخزين جهات الاتصال في حساب المستخدم على Google، ويمكن لمعظم خدمات Google الوصول إلى قائمة جهات الاتصال. يمكن لتطبيق العميل استخدام واجهة برمجة تطبيقات CardDAV لإنشاء جهات اتصال جديدة وتعديل جهات الاتصال الحالية أو حذفها وطلب جهات الاتصال التي تتطابق مع معايير بعينها.
المواصفات
لا يتم تنفيذ المواصفات الكاملة، ولكن يجب أن يعمل العديد من البرامج، مثل Apple iOSTM Contacts (جهات اتصال Apple iOSTM) وmacOS بشكل صحيح.
بالنسبة إلى كل من المواصفات ذات الصلة، في ما يلي دعم CardDAV من Google:
- RFC2518: امتدادات HTTP للكتابة الموزَّعة (WebDAV)
- يتوافق مع طرق HTTP:
GET
وPUT
وDELETE
وOPTIONS
وPROPFIND
. - لا يتوافق مع طرق HTTP،
LOCK
أوUNLOCK
أوCOPY
أوMOVE
أوMKCOL
. - لا يتوافق مع خصائص WebDAV العشوائية (التي يحدّدها المستخدم).
- لا يتوافق مع التحكّم في الوصول إلى WebDAV (RFC3744).
- يتوافق مع طرق HTTP:
- RFC5995: استخدام طريقة POST لإضافة أعضاء إلى مجموعات WebDAV
- يتيح إنشاء جهات اتصال جديدة بدون تحديد معرّف.
- iframe6352: CardDAV: ملحقات {5}vv للكتب الموزَّعة على الويب
والإصدارات (WebDAV)
- يتوافق مع طريقة HTTP
REPORT
، ولكن لا يتم تنفيذ جميع التقارير المحدّدة. - يتيح هذا الخيار توفير مجموعة رئيسية ومجموعة جهات اتصال.
- يتوافق مع طريقة HTTP
- RFC6578: مزامنة المجموعات لـ WebDAV
- ويجب أن تتحول تطبيقات العميل إلى وضع التشغيل هذا بعد المزامنة الأولية.
- RFC6749: إطار عمل تفويض OAuth 2.0 وRFC6750: إطار عمل تفويض OAuth 2.0: استخدام رمز الحامل المميز
- يتيح مصادقة برامج عملاء CardDAV باستخدام مصادقة OAuth 2.0 HTTP. لا تتيح Google أي طريقة أخرى للمصادقة. للحفاظ على أمان بيانات الاتصال، نطلب من اتصالات CardDAV باستخدام بروتوكول HTTPS.
- <!--6764: تحديد خدمات تحديد الموقع الجغرافي لإضافات التقويم على WebDAV (CalDAV) وإضافات ملفات XML إلى WebDAV (CardDAV)
- يجب أن يتم بدء تشغيل عناوين URL لـ CardDAV وفقًا للفقرة 6 من RFC6764.
- يتوافق مع
caldav-ctag-02: علامة كيان جمع التقويم (CTag) في CalDAV،
والتي تتم مشاركتها بين مواصفات CardDAV وCalDAV. جهات الاتصال
ctag
تشبه الموردETag
، وتتغير عند إجراء أي تغيير في دفتر عناوين جهات الاتصال. يسمح هذا لبرنامج العميل أن يحدد بسرعة أنه لا يحتاج إلى مزامنة أي جهات اتصال تم تغييرها. - تستخدم Google الإصدار VCard 3.0 كتنسيق ترميز جهات الاتصال. راجِع: RFC6350: VCard 3.0.
يتطلب CardDAV من Google استخدام OAuth 2.0
تتطلب واجهة CardDAV من Google بروتوكول OAuth 2.0. ارجع إلى الوثائق المرتبطة أدناه للحصول على معلومات حول استخدام OAuth 2.0 للدخول إلى Google APIs:
جارٍ الاتصال بخادم Google CardDAV
يسمح بروتوكول CardDAV باكتشاف دفتر العناوين ومعرفات الموارد المنتظمة (URI) لموارد الاتصال. يجب عدم ترميز أي معرّف موارد منتظم (URI) لأنّه قد يتغيّر في أي وقت.
يجب أن تستخدم تطبيقات العملاء بروتوكول HTTPS، ويجب توفير مصادقة OAuth 2.0
لحساب المستخدم على Google. لن يصادق خادم CardDAV على أحد الطلبات ما لم يصل عبر HTTPS من خلال مصادقة OAuth 2.0 لحساب Google، وإذا كان تطبيقك مسجلاً في DevConsole. وتؤدي أي محاولة للاتصال عبر HTTP باستخدام المصادقة الأساسية أو باستخدام بريد إلكتروني/كلمة مرور غير متطابقين مع حساب Google إلى ظهور رمز الاستجابة HTTP 401 Unauthorized
.
لاستخدام CardDAV، يجب أن يتصل برنامج العميل مبدئيًا بمسار الاستكشاف الأساسي عن طريق تنفيذ HTTP PROPFIND
على:
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. تعمل تطبيقات العميل على الموارد المحددة بواسطة معرفات الموارد المنتظمة (URI) الخاصة بها. تم تحديد بنية معرف الموارد المنتظم (URI) الحالية هنا لمساعدة مطوري البرامج في فهم المفاهيم الواردة في القسم التالي. قد تتغير البنية ويجب ألا يتم ترميزها بشكل ثابت. بل يجب اكتشاف الموارد وفقًا للمعيار RFC.
- مدير المدرسة
- https://www.googleapis.com/carddav/v1/principals/
userEmail
- https://www.googleapis.com/carddav/v1/principals/
- موقع التصوير الرئيسي
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists
- https://www.googleapis.com/carddav/v1/principals/
- دفتر العناوين
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default
- https://www.googleapis.com/carddav/v1/principals/
- التواصل
- https://www.googleapis.com/carddav/v1/principals/
userEmail
/lists/default/contactId
- https://www.googleapis.com/carddav/v1/principals/
مزامنة جهات الاتصال
في ما يلي وصف عام للعمليات المتاحة. وعلى مطوّري البرامج البحث عن التفاصيل في طلب RFC ذي الصلة. يتم ترميز الطلبات والردود في الغالب بتنسيق XML. في ما يلي العمليات الرئيسية التي تستخدمها تطبيقات العميل للمزامنة:
- استخدام علامة CTag
- وتستخدم برامج العملاء طلب
PROPFIND
getctag
في مورد دفتر العناوين لتحديد ما إذا كان قد تم تغيير أي جهة اتصال على الخادم وبالتالي ما إذا كانت هناك حاجة إلى المزامنة أم لا. ومن المضمون أن تتغير قيمة هذه الخاصية في حال تغيير أي جهة اتصال. ويجب أن تخزّن تطبيقات العميل هذه القيمة وتستخدمها فقط في المزامنة الأولية وكإجراء احتياطي في حال إبطالsync-token
. وسيؤدي الاستطلاع الدوري للسمةgetctag
إلى فرض قيود على المحتوى.
- وتستخدم برامج العملاء طلب
- استخدام الرمز المميّز للمزامنة
- تستخدم برامج العملاء طلب
PROPFIND
الخاص بـsync-token
في دفتر العناوين للحصول علىsync-token
التي تمثّل حالتها الحالية. ويجب أن تخزّن تطبيقات العملاء هذه القيمة وتُصدر طلباتsync-collection
REPORT
الدورية لتحديد التغييرات منذ آخر إصدارsync-token
. تكون الرموز المميّزة التي يتم إصدارها صالحة لمدة 29 يومًا، وسيتضمّن الردّREPORT
رمزsync-token
جديدًا.
- تستخدم برامج العملاء طلب
- استخدام علامات ETag
- تُصدر تطبيقات العميل طلب
PROPFIND
getetag
في مورد دفتر العناوين (بعنوان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) الخاص بجهة الاتصال.
- تحذف تطبيقات العملاء جهة اتصال من خلال إصدار طلب