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

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

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

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

المواصفات

في ما يلي مواصفات دعم 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 Console من خلال إنشاء مشروع.

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

عليك بعد ذلك تفعيل CalDAV API.

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

  1. افتح مكتبة واجهات برمجة التطبيقات في 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