تخصيص API: تجاوز نقاط الوصول وعمليات Webhook

Premium

تخصيص API: شاشة متقدمة مخصصة لقسم تقنية المعلومات، تتيح إعادة توجيه نقطة وصول في API إلى خادم آخر (وكيل، إدارة CORS، خادم خاص) وتشغيل عمليات Webhook — أي استدعاءات صادرة نحو نظامكم — عند كل تعديل في جدول زمني أو معلم أو مادة. متاحة في حسابات Premium، خلف مصادقة معززة.

تخصيص API شاشة تقنية موجهة إلى قسم تقنية المعلومات. تتيح تكييف سلوك API الخاص بـ Omniscol لحسابكم عبر ثلاث وسائل:

  • الإعداد العام (ترويسات HTTP مشتركة)؛
  • تجاوز نقطة وصول — إعادة توجيه تطبيق الويب إلى عنوان URL آخر، أو تعطيل نقطة وصول؛
  • عمليات Webhook — استدعاءات صادرة يرسلها Omniscol إلى نظامكم عند إجراء عملية ما.

أين تجدونه

وحدة الإدارة، شاشة استيراد / تصدير، قسم تخصيص API، الزر API.

الشاشة مخصصة لحسابات Premium ومحمية بـ مصادقة معززة: يطلب Omniscol من جديد كلمة مرور المسؤول قبل فتح النافذة. ولأن كل إجراء في هذه الشاشة يمس العقد التقني لتكاملكم، فإن إعداده يتم بالتنسيق مع Omniscol.

الإعداد العام

تحددون هنا ترويسات HTTP (بالصيغة clé1:valeur1;clé2:valeur2) تُطبَّق على جميع عمليات Webhook. وهذا هو المكان الطبيعي لوضع رمز مصادقة موجه إلى خادمكم الخاص (مثل Authorization: Bearer … الذي ينتظره خادمكم). أما في حالة التجاوز، فتوضع المصادقة في الترويسات الخاصة بنقطة الوصول (انظروا أدناه).

تجاوز نقطة وصول

يعيد التجاوز تعريف نقطة وصول في API الخاص بـ Omniscol بحيث يستدعي تطبيق الويب عنوان URL آخر بدلا منها. ثلاثة استخدامات، من الأقوى إلى الأبسط.

تقديم بيانات مباشرة من نظام المعلومات لديكم

هذا هو الاستخدام الأقوى. تعيدون توجيه نقطة وصول في القراءة إلى عنوان URL خارجي — عادة أداة ETL تربط نظام المعلومات الداخلي لمؤسستكم. يجلب تطبيق الويب حينئذ البيانات مباشرة من هذا النظام، بدلا من النسخة المحلية التي يحتفظ بها Omniscol.

عمليا: عندما يكون عنوان إعادة التوجيه عنوانا خارجيا مطلقا، يستدعيه تطبيق الويب مباشرة، دون المرور بخوادم Omniscol، ويستهلك الإجابة كما هي — تماما كما لو كانت صادرة عن Omniscol. القيد الوحيد هو أن يجيب نظامكم بالصيغة التي ينتظرها Omniscol لنقطة الوصول هذه (بنية JSON نفسها): لا يوجد أي تحويل وسيط. بالنسبة إلى نقطة الوصول هذه، لا يعود يُستعلم عن النسخة المحلية في Omniscol؛ والبيانات المعروضة هي بيانات نظامكم الحية.

مثال: فهرس المواد في المؤسسة يُقدَّم عند الطلب من نظام المعلومات لديكم، بحيث يظهر في Omniscol فورا كل تحديث يجري في المدرسة، دون إعادة استيراد.

تُوضع المصادقة إلى نظامكم هنا في الترويسات الخاصة بنقطة الوصول (مثل Authorization: Bearer …)، وتُدخل في سطر التجاوز. ويمكن أيضا فرض طريقة HTTP لكل نقطة وصول.

إعادة ربط نقطة وصول في التطبيق نفسه بمصدر خارجي حي إمكانية قوية بقدر ما هي صعبة: يجب التعامل معها بالتنسيق مع قسم تقنية المعلومات لديكم ومع Omniscol.

إدراج خادمكم الخاص أو وكيل

يمكنكم أيضا تمرير الاستدعاءات عبر خادمكم الخاص أو وكيل — مثلا للسماح بمشاركة الموارد بين المصادر المختلفة (CORS)، أو لإدراج منطق خاص بكم بين تطبيق الويب وOmniscol.

تعطيل نقطة وصول

تعطلون نقطة وصول بعدم منحها أي عنوان URL لإعادة التوجيه (الطريقة null).

قدّروا الأثر على الواجهة. Omniscol تطبيق ويب أحادي الصفحة (SPA) تتحكم في عناصر واجهته نقاط الوصول المتاحة: لا تظهر الأزرار والتبويبات والقوائم إلا إذا كانت نقطة الوصول التي تعتمد عليها موجودة. لذلك فإن تعطيل نقطة وصول يؤدي إلى اختفاء عناصر الواجهة التي تعتمد عليها ديناميكيا عند العرض التالي — وإذا عطلتم جميع نقاط الوصول في وحدة ما، تختفي الوحدة بأكملها من التنقل. هذه العناصر تُزال ولا تُخفى فقط، ويتم ذلك كله دون أي تدخل في الشيفرة: يكفي تعديل الإعداد وإعادة تحميل التطبيق.

يسرد الجدول، لكل نقطة وصول: مفتاحها (الرمز الداخلي للعملية)، وعنوان URL الأصلي، وطريقة HTTP، وعنوان URL الجديد لإعادة التوجيه، وترويسات خاصة. ويتيح حقل بحث العثور على نقطة الوصول المراد تجاوزها.

عمليات Webhook (الاستدعاءات الصادرة)

يطلب Webhook من Omniscol إرسال طلب HTTP إلى عنوان URL الخاص بكم بعد نجاح عملية ما. وهو الآلية المناسبة لإبقاء نظام خارجي على اطلاع في الزمن الفعلي — لوحة عرض، أو فضاء عمل رقمي، أو نظام موارد بشرية، أو مزامنة خاصة بكم…

يُربط Webhook بطريقتين:

  • بـ نقطة وصول محددة (مفتاح العملية)؛
  • بـ حدث مجمّع، يغطي دفعة واحدة مجموعة من العمليات. توجد ثلاثة أحداث مجمّعة:
    • تعديل جدول زمني — أي تغيير يمس الجدول الزمني الساري، بما فيه الآثار الجانبية: حفظ جدول زمني، وإنشاء حصص أو نقلها أو حذفها، ونشر جدول زمني، وغيابات المعلمين أو الصفوف بمجرد أن يُمس تاريخ، والإزالات البنيوية (قاعة، مادة…) في جدول زمني منشور — فحذف مادة يحذف الحصص التي كانت تستخدمها، وهو تغيير في حد ذاته. أما التعديلات المقتصرة على مسودة غير منشورة فلا تشغّله؛
    • تعديل معلم (إضافة أو تحديث أو حذف)؛
    • تعديل مادة (المواد المخصصة).

لكل Webhook، تدخلون عنوان URL لاستدعاء الرد، وطريقة HTTP، ومربع الاختيار "مع البيانات" (هل يجب إرفاق محتوى الطلب الأصلي؟)، وترويسات خاصة.

ما يتلقاه خادمكم

يُرسل الاستدعاء بالصيغة application/json ويحمل، إضافة إلى ترويساتكم:

  • محتوى الطلب الأصلي إذا كان الخيار "مع البيانات" مفعلا؛
  • كتلة بيانات وصفية من Omniscol: عنوان URL المستدعى، ورمز نقطة الوصول، والطريقة، والمعاملات، ورمز مصادقة المستخدم، ومعرّف المؤسسة، وإعداد الـ Webhook نفسه؛
  • ترويسات للتتبع: X-OS-original-query وX-OS-original-endpoint وX-OS-auth وX-School.

بالنسبة إلى الحدث تعديل جدول زمني، وعندما يكون الخيار "مع البيانات" مفعلا، يتضمن الاستدعاء أيضا فروقا في الحصص (الحصص المضافة والمعدلة والمحذوفة) — وهذا مفيد لنشر ما تغير فقط.

السلوك

تنطلق عمليات Webhook في الخلفية، بعد نجاح عملية المستخدم: فهي لا تبطئ الواجهة ولا تعطلها إذا فشل خادمكم. الاستدعاء الصادر الذي لا ينجح يُسجَّل دون مقاطعة العمل في Omniscol. ولكل استدعاء مهلة انتهاء قصيرة (بضع ثوان): يجب أن يؤكد خادمكم الاستلام بسرعة وأن ينفذ بقية المعالجة من جانبه.

جيد أن تعرفوا

  • يعرض API الخاص بـ Omniscol مجموعة فرعية من العمليات؛ ولا ينطبق التجاوز أو Webhook إلا على نقاط الوصول المعروضة فعلا. راجعوا API Omniscol للاطلاع على القائمة وعلى المصادقة.
  • بالنسبة إلى التكامل مع برنامج متكامل (ERP، نظام موارد بشرية، فضاء عمل رقمي)، غالبا ما تكون المزامنة المخصصة أنسب — راجعوا المزامنة مع الأنظمة الخارجية. ويُستخدم نظام Webhook نفسه داخليا.
  • لكي يطلع وكيل ذكاء اصطناعي على بياناتكم دون تطوير، راجعوا MCP — ربط وكيل ذكاء اصطناعي خارجي.

انظر أيضًا