دليل مطوّري برامج واجهة برمجة تطبيقات 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: iCalendar
  • يتم تنسيق البيانات المعروضة في واجهة CalDAV وفقًا لمواصفات iCalendar.
  • لا تتوافق حاليًا مع بيانات VTODO أو VJOURNAL.
  • لا يدعم ملحق Apple iCal® للسماح بمواقع عناوين URL التي يمكن للمستخدم تعيينها.
• rfc6578: مزامنة المجموعات WebDAV
  • يجب تبديل تطبيقات العميل إلى وضع التشغيل هذا بعد المزامنة الأولية.
• rfc6638: جدولة إضافات إلى CalDAV
  • يدعم "البريد الوارد" البسيط الذي يكون فارغًا دائمًا.
  • يتم تلقائيًا تسليم الدعوات التي تتلقاها إلى مجموعة "الأحداث" بدلاً من وضعها في "صندوق البريد".
  • لا يدعم البحث عن الحالة متوفّر/مشغول.
• caldav-ctag-02: علامة كيان مجموعة التقويم (CTag) في CalDAV
  • التقويم ctag هو مورد etag، حيث يتغير عند تغيير أي شيء في التقويم. وهذا يسمح لتطبيق العميل بتحديد سريع أنه لا يحتاج إلى مزامنة أي أحداث تم تغييرها.
• proxy-proxy: وظائف وكيل مستخدم "تقويم Google" في CalDAV
  • لتحسين أداء مزامنة التقويم من أجهزة iOS التي لا توفّر التفويض، لن تتمكّن من استخدام السمتَين calendar-proxy-read-for أو calendar-proxy-write-for مع وكيل مستخدم iOS.

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

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

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

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

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

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

الخطوة التالية هي تفعيل CalDAV API.

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

1. افتح مكتبة واجهة برمجة التطبيقات في وحدة تحكم واجهة برمجة تطبيقات Google. اختَر مشروعًا أو أنشئ مشروعًا جديدًا إذا طُلب منك ذلك. تدرج مكتبة واجهة برمجة التطبيقات جميع واجهات برمجة التطبيقات المتاحة، مجمّعة بحسب عائلة المنتج وشعبيتها.
2. إذا كانت واجهة برمجة التطبيقات التي تريد تمكينها غير مرئية في القائمة، فاستخدم البحث للعثور عليها.
3. حدد واجهة برمجة التطبيقات التي تريد تمكينها، ثم انقر على الزر تمكين.
4. فعِّل الفوترة إذا طُلب منك ذلك.
5. اقبل بنود خدمة واجهة برمجة التطبيقات إذا طُلب منك ذلك.

لتنفيذ طلبات واجهة برمجة تطبيقات CalDAV ستحتاج إلى معرّف العميل وسر العميل.

للعثور على معرِّف العميل لمشروعك وسر العميل، نفذ ما يلي:

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) يتطلّب مجموعة رئيسية كنقطة البداية، يكون معرّف الموارد المنتظم الذي يتم الربط به هو:

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. .