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

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

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

تنطبق حدود الحصة نفسها على CalDAV API كما تنطبق على Calendar API. لمزيد من المعلومات، يُرجى الاطّلاع على حدود الاستخدام.

المواصفات

بالنسبة إلى كل المواصفات ذات الصلة، يكون توافق 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 Access Control (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: Scheduling Extensions to CalDAV

    • يتيح استخدام "بريد وارد" بسيط يكون فارغًا دائمًا.
    • يتم تلقائيًا إرسال الدعوات التي تتلقّاها إلى مجموعة "الأحداث" بدلاً من وضعها في "البريد الوارد".
    • لا يتيح البحث عن free-busy.

  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

    • التقويم ctag يشبه المورد etag، ويتغير عند حدوث أي تغيير في التقويم. ويتيح ذلك لتطبيق العميل أن يحدّد بسرعة أنّه لا يحتاج إلى مزامنة أي أحداث تم تغييرها.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • لتحسين أداء مزامنة التقويم، ستتعذّر الطلبات التي تتضمّن السمتَين calendar-proxy-read-for أو calendar-proxy-write-for مع UserAgent لنظام التشغيل iOS لأنّ أجهزة iOS لا تتيح التفويض.

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

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

لاستخدام CalDAV API، يجب أن يكون لديك حساب Google.

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

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

عليك بعد ذلك تفعيل واجهة برمجة تطبيقات CalDAV.

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

  1. افتح مكتبة API في Google API Console. إذا طُلب منك ذلك، اختَر مشروعًا أو أنشئ مشروعًا جديدًا. تعرض "مكتبة واجهات برمجة التطبيقات" جميع واجهات برمجة التطبيقات المتاحة، ويتم تجميعها حسب فئة المنتج ومدى رواجها.
  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/CALENDAR_ID/user

استبدِل CALENDAR_ID بمعرّف التقويم الذي تريد الوصول إليه.

للعثور على معرّف التقويم من خلال واجهة الويب، اختَر **إعدادات التقويم** من القائمة المنسدلة بجانب اسم التقويم. يظهر معرّف التقويم في قسم بعنوان عنوان التقويم. معرّف التقويم الرئيسي للمستخدم هو نفسه عنوان البريد الإلكتروني الخاص به.

إذا كان برنامج العميل (مثل Mozilla Thunderbird) يتطلب مجموعة تقاويم كنقطة بداية، استخدِم معرّف الموارد المنتظم (URI) التالي:

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