إدارة جهات الاتصال باستخدام بروتوكول 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" (mailto3744).
• RFC5995: استخدام طريقة POST لإضافة أعضاء إلى مجموعات WebDAV
  • يتيح إنشاء جهات اتصال جديدة بدون تحديد معرّف.
• height6352: CardDAV: vCard إضافات إلى التأليف الموزَّع على الويب و تحديد الإصدارات (WebDAV)
  • تتيح طريقة HTTP REPORT، ولكن لا تتوفر بعض التقارير المحددة تنفيذها.
  • يتيح توفير المجموعة الرئيسية ومجموعة جهات الاتصال.
• RFC6578: مزامنة مجموعات WebDAV
  • يجب تبديل تطبيقات العملاء إلى وضع التشغيل هذا بعد المزامنة الأولية.
• RFC6749: إطار عمل التفويض OAuth 2.0 RFC6750: إطار عمل تفويض OAuth 2.0: استخدام رمز الحامل المميز
  • إتاحة مصادقة برامج عميل CardDAV باستخدام بروتوكول OAuth 2.0 HTTP المصادقة. لا تتيح Google استخدام أي طريقة أخرى للمصادقة. للحفاظ على أمان بيانات جهات الاتصال، نشترط استخدام اتصالات CardDAV. HTTPS.
• RFC6764: تحديد موقع الخدمات الخاصة بإضافات التقويم في إضافات WebDAV (CalDAV) و vCard مع إضافات WebDAV (CardDAV)
  • يجب أن يتم تجميع عينات عشوائية لعناوين URL لـ CardDAV وفقًا للفقرة 6 من mailto6764.
• يدعم 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:

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

الاتصال بخادم CardDAV من Google

يسمح بروتوكول CardDAV باكتشاف دفتر العناوين وموارد جهات الاتصال معرّفات الموارد المنتظمة (URI). يجب عدم إجراء ترميز ثابت لأي عنوان URI، إذ يمكن أن يتغير في أي وقت.

يجب أن تستخدم تطبيقات العملاء بروتوكول HTTPS، ويجب أن تكون مصادقة OAuth 2.0 متوافقة المقدمة لحساب المستخدم على Google. لن يتمكن خادم CardDAV مصادقة أحد الطلبات ما لم يصل عبر HTTPS من خلال OAuth 2.0 مصادقة حساب Google، وتم تسجيل طلبك في وحدة تحكم مطوّري البرامج أي محاولة للاتصال عبر 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. وتعمل تطبيقات العميل على الموارد التي التي تحددها معرّفات الموارد المنتظمة (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
  • تستخدم برامج العملاء طلب 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 لجهة الاتصال.