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

‫CalDAV هي إضافة إلى WebDAV توفّر معيارًا للبرامج للوصول إلى معلومات التقويم على خادم بعيد.

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

المواصفات

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

• rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
  • يتوافق مع طرق HTTP‏ GET وPUT وHEAD وDELETE وPOST وOPTIONS وPROPFIND وPROPPATCH.
  • لا تتوافق مع طرق HTTP‏ LOCK أو UNLOCK أو COPY أو MOVE أو MKCOL، أو العنوان If* (باستثناء If-Match).
  • لا تتوافق مع سمات WebDAV العشوائية (التي يحدّدها المستخدم).
  • لا تتوافق مع عناصر التحكّم في الوصول إلى WebDAV (rfc3744).
• rfc4791: Calendaring Extensions to WebDAV (CalDAV)
  • يتوافق مع طريقة HTTP REPORT. تم تنفيذ جميع التقارير باستثناء تقرير free-busy-query.
  • لا تتوافق مع طريقة HTTP MKCALENDAR.
  • لا يتيح تنفيذ الإجراء AUDIO.
• rfc5545: iCalendar
  • يتم تنسيق البيانات المعروضة في واجهة CalDAV وفقًا لمواصفات iCalendar.
  • لا تتوافق حاليًا مع بيانات VTODO أو VJOURNAL.
  • لا تتوافق مع إضافة Apple iCal® للسماح بضبط خصائص عناوين URL من قِبل المستخدم.
• rfc6578: Collection Synchronization for WebDAV
  • يجب أن تنتقل تطبيقات العميل إلى وضع التشغيل هذا بعد المزامنة الأولية.
• rfc6638: إضافات الجدولة إلى CalDAV
  • يتيح استخدام "صندوق وارد" بسيط يكون فارغًا دائمًا.
  • يتم تلقائيًا تسليم الدعوات التي تتلقّاها إلى مجموعة "الأحداث" بدلاً من وضعها في "البريد الوارد".
  • لا يتيح البحث عن أوقات التوفّر والانشغال.
• caldav-ctag-02: علامة كيان مجموعة التقويم (CTag) في CalDAV
  • التقويم ctag يشبه المورد etag، ويتغيّر عند حدوث أي تغيير في التقويم. يتيح ذلك لتطبيق العميل تحديد أنّه لا يحتاج إلى مزامنة أي أحداث تم تغييرها بسرعة.
• calendar-proxy: وظيفة وكيل مستخدم "تقويم Google" في CalDAV
  • لتحسين أداء مزامنة التقويم من أجهزة iOS التي لا تتيح التفويض، لن ينجح استخدام السمتَين calendar-proxy-read-for أو calendar-proxy-write-for مع UserAgent لنظام التشغيل iOS.

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

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

إنشاء معرّف العميل

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

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

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

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

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

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

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.