إدارة جهات الاتصال باستخدام بروتوكول CardDAV

يمكنك عرض جهات اتصالك وإدارتها باستخدام بروتوكول CardDAV من Google.

يتم تخزين جهات الاتصال في حساب المستخدم على Google، ويمكن لمعظم خدمات Google الوصول إلى قائمة جهات الاتصال. يمكن لتطبيق العميل استخدام واجهة برمجة تطبيقات CardDAV لإنشاء جهات اتصال جديدة وتعديل جهات الاتصال الحالية أو حذفها وطلب جهات الاتصال التي تتطابق مع معايير بعينها.

المواصفات

لا يتم تنفيذ المواصفات الكاملة، ولكن يجب أن يعمل العديد من البرامج، مثل Apple iOSTM Contacts (جهات اتصال Apple iOSTM) وmacOS بشكل صحيح.

بالنسبة إلى كل من المواصفات ذات الصلة، في ما يلي دعم CardDAV من Google:

يتطلب 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.

  1. مدير المدرسة
    • https://www.googleapis.com/carddav/v1/principals/userEmail
  2. موقع التصوير الرئيسي
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists
  3. دفتر العناوين
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default
  4. التواصل
    • https://www.googleapis.com/carddav/v1/principals/userEmail/lists/default/contactId

مزامنة جهات الاتصال

في ما يلي وصف عام للعمليات المتاحة. وعلى مطوّري البرامج البحث عن التفاصيل في طلب 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) الخاص بجهة الاتصال.