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

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

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

للبحث عن معرِّف العميل وسر العميل لمشروعك، قم بما يلي:

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