دليل مطوري واجهة برمجة تطبيقات 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تقويم
    • يتم تنسيق البيانات المعروضة في واجهة CalDAV وفقًا لمواصفات icalendar.
    • لا تتيح حاليًا استخدام بيانات VTODO أو VJOURNAL.
    • لا تتوافق مع الإضافة Apple iCal® للسماح بخصائص عنوان URL التي يمكن للمستخدم ضبطها.
  • RFC6578: مزامنة مجموعات WebDAV
    • يجب أن تتحول تطبيقات العميل إلى وضع التشغيل هذا بعد المزامنة الأولية.
  • mailto6638: جدولة الإضافات في CalDAV
    • يتيح "صندوق بريد" تافه يكون فارغًا دائمًا.
    • يتم تسليم الدعوات التي تتلقاها تلقائيًا إلى مجموعة "الفعاليات" بدلاً من وضعها في "البريد الوارد".
    • لا يتيح البحث في حالتَي متوفّر/مشغول.
  • caldav-ctag-02: علامة كيان جمع التقويم (CTag) في CalDAV
    • يشبه التقويم ctag مورد etag، حيث يتغير عندما يتغير أي شيء في التقويم. ويسمح هذا لتطبيق العميل بتحديد أنّه لا يحتاج إلى مزامنة أي أحداث تم تغييرها.
  • calendar-proxy: وظائف الخادم الوكيل لمستخدم "تقويم Google" في CalDAV
    • لتحسين أداء مزامنة التقويم من أجهزة iOS التي لا تتوافق مع التفويض، لن يكون بالإمكان استخدام السمتَين calendar-proxy-read-for أو calendar-proxy-write-for مع وكيل مستخدم iOS.

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

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

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

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

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

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

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

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

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

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

  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 أو استخدام "المصادقة الأساسية" إلى ظهور رمز حالة 401 Unauthorized HTTP.

إذا كان برنامج العميل (مثل تطبيق التقويم من 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.