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

CalDAV هو امتداد من WebDAV يوفر معيارًا للعملاء للوصول إلى معلومات التقويم على خادم بعيد.

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

المواصفات

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

• RFC4918: إضافات HTTP للكتابة وتحديد الإصدارات الموزعة على الويب (WebDAV)
  • يتوافق هذا الخيار مع طرق HTTP GET وPUT وHEAD وDELETE وPOST وOPTIONS وPROPFIND وPROPPATCH.
  • لا يتوافق مع طرق HTTP LOCK أو UNLOCK أو COPY أو MOVE أو MKCOL، أو عنوان If* (باستثناء If-Match).
  • لا يتوافق مع خصائص WebDAV العشوائية (التي يحددها المستخدم).
  • لا يتوافق مع التحكم في الوصول لـ WebDAV (RFC3744).
• RFC4791: إضافات التقويم إلى WebDAV (CalDAV)
  • وتتوافق هذه الخدمة مع طريقة HTTP REPORT. يتم تنفيذ جميع التقارير باستثناء طلب بحث الحالة "متوفّر-مشغول".
  • لا يتوافق هذا الخيار مع طريقة HTTP MKCALENDAR.
  • لا يدعم الإجراء AUDIO.
• RFC5545: iالتقويم
  • يتم تنسيق البيانات المكشوفة في واجهة CalDAV وفقًا لمواصفات icalendar.
  • لا تدعم حاليًا بيانات VTODO أو VJOURNAL.
  • لا يمكن استخدام الإضافة Apple iCal® للسماح بخصائص عناوين URL التي يمكن للمستخدم ضبطها.
• RFC6578: مزامنة المجموعات لـ WebDAV
  • ويجب أن تتبدّل تطبيقات العميل إلى وضع التشغيل هذا بعد المزامنة الأولية.
• RFC6638: جدولة الإضافات إلى CalDAV
  • تدعم "صندوق بريد" تافهًا، والذي يكون فارغًا دائمًا.
  • ويتم تسليم الدعوات التي تتلقاها تلقائيًا في مجموعة "الأحداث" بدلاً من وضعها في "البريد الوارد".
  • لا يدعم البحث عن الحالة موجود/مشغول.
• caldav-ctag-02: علامة الكيان لجمع التقويم (CTag) في CalDAV
  • يشبه تقويم ctag موردًا etag، حيث يتغير عند إجراء أي تغيير على أي شيء في التقويم. ويتيح ذلك لتطبيق العميل التحديد سريعًا أنّه لا يحتاج إلى مزامنة أي أحداث تم تغييرها.
• calendar-proxy: وظيفة الخادم الوكيل لمستخدم التقويم في CalDAV
  • لتحسين أداء مزامنة التقويم من أجهزة iOS التي لا تتوافق مع ميزة التفويض، سيتعذّر استخدام السمتَين calendar-proxy-read-for أو calendar-proxy-write-for مع UserAgent لنظام التشغيل iOS.

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

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

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

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

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

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

تتمثل الخطوة التالية في تفعيل واجهة برمجة تطبيقات CalDAV.

لتفعيل واجهة برمجة تطبيقات لمشروعك، يمكنك إجراء ما يلي:

1. افتح مكتبة واجهة برمجة التطبيقات في وحدة تحكم واجهة برمجة تطبيقات Google. إذا طُلب منك ذلك، حدد مشروعًا أو أنشئ مشروعًا جديدًا. تسرد مكتبة واجهة برمجة التطبيقات جميع واجهات برمجة التطبيقات المتاحة، مجمّعة حسب مجموعة المنتجات ومدى الرواج.
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 iCal) يتطلب مجموعة رئيسية كنقطة بداية، سيكون معرّف الموارد المنتظم (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. .