دليل مطوري واجهة برمجة تطبيقات CalDAV

ويُعد CalDAV امتدادًا لـ WebDAV يوفر معيارًا للعملاء للوصول معلومات التقويم على خادم بعيد.

توفّر Google واجهة CalDAV يمكنك استخدامها لعرض التقاويم وإدارتها باستخدام بروتوكول CalDAV.

المواصفات

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

  • SUBJECT4918: إضافات HTTP للتأليف الموزع على الويب وتحديد الإصدارات (WebDAV)
    • تتيح هذه السياسة استخدام طرق HTTP التالية: GET وPUT وHEAD وDELETE وPOST OPTIONS وPROPFIND وPROPPATCH
    • لا يتيح استخدام طرق HTTP التالية: LOCK أو UNLOCK أو COPY أو MOVE أو MKCOL، أو عنوان If* (باستثناء If-Match).
    • ولا تتوافق مع خصائص WebDAV العشوائية (من تحديد المستخدم).
    • لا يتوافق مع التحكم في الوصول إلى WebDAV (mailto3744).
  • RFC4791: إضافة تقويم إلى WebDAV (CalDAV)
    • يتيح استخدام طريقة HTTP REPORT. جميع التقارير باستثناء طلب بحث الحالة "متوفّر-مشغول" تنفيذها.
    • لا يتيح استخدام طريقة HTTP MKCALENDAR.
    • لا يتوافق مع الإجراء AUDIO.
  • SUBJECT5545: iتقويم Google
    • يتم تنسيق البيانات المعروضة في واجهة CalDAV وفقًا مواصفات icalendar.
    • لا تتيح حاليًا استخدام بيانات VTODO أو VJOURNAL.
    • لا تتوافق مع الإضافة Apple iCal® للسماح بخصائص عنوان URL التي يمكن للمستخدم ضبطها.
  • RFC6578: مزامنة مجموعات WebDAV
    • يجب تبديل تطبيقات العملاء إلى وضع التشغيل هذا بعد المزامنة الأولية.
  • RFC6638: جدولة الإضافات في CalDAV
    • تدعم "صندوق بريد" تافهًا والتي تكون فارغة دائمًا.
    • يتمّ تلقائيًا تسليم الدعوات التي تتلقّاها إلى "الفعاليات" بدلاً من وضعها في "البريد الوارد".
    • لا يتيح البحث في حالتَي متوفّر/مشغول.
  • caldav-ctag-02: علامة كيان جمع التقويم (CTag) في CalDAV
    • يشبه التقويم ctag المورد etag؛ يتغير عندما يكون أي شيء في التقويم. يسمح هذا لتطبيق العميل تحدد بسرعة أنها لا تحتاج إلى مزامنة أي تغييرات أحداث.
  • calendar-proxy: وظائف الخادم الوكيل لمستخدم "تقويم Google" في CalDAV
    • لتحسين أداء مزامنة التقويم من أجهزة iOS، لا تدعم التفويض، وذلك باستخدام calendar-proxy-read-for أو لن تنجح خصائص calendar-proxy-write-for التي تستخدم وكيل مستخدم iOS.

لم نقم حتى الآن بتنفيذ كامل والمواصفات. ومع ذلك، بالنسبة للعديد من البرامج مثل تطبيق التقويم من Apple ينبغي أن يعمل بروتوكول CalDAV بشكل صحيح.

ملاحظة: للحفاظ على أمان الحساب ولمنع إساءة الاستخدام، قد تضبط ملفات تعريف الارتباط على تطبيقات العميل التي تصل إلى البيانات عبر CalDAV.

إنشاء معرّف العميل الخاص بك

لاستخدام CalDAV API، يجب أن يكون لديك حساب Google إذا كان لديك حساب يمكنك استخدامه، لست بحاجة إلى اتخاذ أي إجراء.

قبل إرسال طلبات إلى CalDAV API، عليك تسجيل عميلك باستخدام وحدة التحكم في واجهة Google API من خلال إنشاء مشروع.

انتقِل إلى وحدة التحكم في واجهة Google API. انقر على إنشاء مشروع. أدخِل اسمًا وانقر على إنشاء.

الخطوة التالية هي تفعيل CalDAV API.

لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:

  1. افتح مكتبة واجهة برمجة التطبيقات في وحدة التحكم في واجهة Google API. إذا طُلب منك، اختَر أو إنشاء مشروع جديد. تسرد مكتبة واجهة برمجة التطبيقات جميع البيانات المتاحة واجهات برمجة التطبيقات، مجمّعة حسب مجموعة المنتجات ومدى رواجها
  2. إذا لم تكن واجهة برمجة التطبيقات التي تريد تفعيلها ظاهرة في القائمة، استخدِم ميزة البحث من أجل العثور عليها.
  3. اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على تفعيل. .
  4. فعِّل الفوترة إذا طُلب منك ذلك.
  5. اقبل بنود خدمة واجهة برمجة التطبيقات إذا طُلب منك ذلك.
لتنفيذ طلبات CalDAV API، ستحتاج إلى معرِّف العميل وسر العميل.

للعثور على معرِّف العميل وسر العميل لمشروعك، عليك اتّباع الخطوات التالية:

  1. اختيار بروتوكول OAuth 2.0 حالي بيانات الاعتماد أو افتح صفحة بيانات الاعتماد.
  2. أنشئ OAuth 2.0 لمشروعك إذا لم يسبق لك إجراء ذلك. بيانات الاعتماد بالنقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth توفير المعلومات اللازمة لإنشاء بيانات الاعتماد.
  3. ابحث عن معرِّف العميل في قسم معرّفات عميل OAuth 2.0. لمعرفة التفاصيل، انقر على معرِّف العميل.

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

لاستخدام واجهة CalDAV، يتصل برنامج عميل في البداية خادم تقويم في إحدى نقطتي البداية. في كلتا الحالتين، أن يتم إنشاؤها عبر HTTPS وأن تستخدم OAuth 2.0 نظام المصادقة. سيرفض خادم CalDAV مصادقة أحد الطلبات ما لم يصل عبر HTTPS من خلال مصادقة OAuth 2.0 لحساب Google. تؤدي محاولة الاتصال عبر HTTP أو استخدام "المصادقة الأساسية" إلى ظهور بروتوكول HTTP رمز الحالة 401 Unauthorized.

إذا كان برنامج العميل (مثل تطبيق التقويم من Apple) يتطلب المجموعة الرئيسية كنقطة بداية، فإن معرف الموارد المنتظم (URI) المطلوب الاتصال به هو:

https://apidata.googleusercontent.com/caldav/v2/calid/user

أين يجب استبدال calid بعلامة "معرّف التقويم" من التقويم للوصول إليه. يمكن العثور على ذلك من خلال واجهة الويب لتقويم Google على النحو التالي: في القائمة المنسدلة بجوار اسم التقويم، اختر إعدادات التقويم. في الصفحة التي ستظهر لك يظهر معرِّف التقويم في قسم يحمل الاسم التقويم العنوان. معرف التقويم للتقويم الأساسي للمستخدم هو نفسه عنوان البريد الإلكتروني لهذا المستخدم.

إذا كان هناك برنامج عميل (مثل Mozilla Sunbird) يتطلب مجموعة التقويم كنقطة بداية، فإن معرف الموارد المنتظم (URI) المطلوب الاتصال به هو:

https://apidata.googleusercontent.com/caldav/v2/calid/events

نقطة النهاية القديمة https://www.google.com/calendar/dav هي متوقّفة نهائيًا ولم تعُد متاحة واستخدامها على مسؤوليتك الخاصة. ننصحك بالانتقال إلى تنسيق نقطة النهاية الجديد الموضّح أعلاه.

iCal® هي علامة تجارية لشركة Apple Inc.