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

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

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

المواصفات

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

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

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

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

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

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

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

انتقِل إلى وحدة التحكم في واجهة 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) يتطلّب مجموعة تقويم كنقطة بداية، يكون معرّف الموارد المنتظم المطلوب الاتصال به هو:

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

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

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