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

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

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

المواصفات

لم يتم تنفيذ المواصفات الكاملة، ولكن العديد من العملاء مثل جهات اتصال Apple iOSTM وأن يعمل نظام التشغيل macOS بشكل صحيح.

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

• SUBJECT2518: إضافات HTTP للتأليف الموزَّع (WebDAV)
  • تتيح طرق HTTP GET وPUT وDELETE وOPTIONS و PROPFIND.
  • لا يتوافق مع طرق HTTP التالية: LOCK أو UNLOCK أو COPY أو MOVE أو MKCOL
  • لا يتوافق مع خصائص WebDAV العشوائية (من تحديد المستخدم).
  • لا يتوافق مع WebDAV Access Control (rfc3744).
• rfc5995: استخدام POST لإضافة أعضاء إلى مجموعات WebDAV
  • يتيح إنشاء جهات اتصال جديدة بدون تحديد معرّف.
• height6352: CardDAV: vCard إضافات إلى التأليف الموزع على الويب و تحديد الإصدارات (WebDAV)
  • تتيح طريقة HTTP REPORT، ولكن لا يتم تنفيذ بعض التقارير المحدّدة.
  • يتيح توفير المجموعة الرئيسية ومجموعة جهات الاتصال.
• rfc6578: مزامنة المجموعة لخدمة WebDAV
  • يجب أن تبدِّل تطبيقات العميل إلى وضع التشغيل هذا بعد التكامل المبدئي.
• RFC6749: إطار عمل التفويض OAuth 2.0 RFC6750: إطار عمل تفويض OAuth 2.0: استخدام رمز الحامل المميز
  • يتيح مصادقة برامج عملاء CardDAV باستخدام مصادقة بروتوكول HTTP OAuth 2.0. لا تتيح Google استخدام أي طريقة أخرى للمصادقة. للحفاظ على أمان بيانات جهات الاتصال، نطلب استخدام بروتوكول HTTPS في اتصالات CardDAV.
• RFC6764: تحديد موقع الخدمات الخاصة بإضافات التقويم في إضافات WebDAV (CalDAV) و vCard مع إضافات 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:

• استخدام OAuth 2.0 للوصول إلى Google APIs
• استخدام بروتوكول OAuth 2.0 للتطبيقات المثبَّتة

الاتصال بخادم 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.

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
  • تستخدم برامج العملاء طلب 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 لجهة الاتصال.