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

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

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

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

المواصفات

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

  • ‫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 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/CALENDAR_ID/user

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

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

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

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