الاستخدام الأمثل لـ API: التخزين المؤقت وحدود معدل الطلبات وعمليات Webhook
Premiumعندما يستعلم تكامل ما من Omniscol كل دقيقة ليعرف هل تغيرت البيانات، فإنه يتلقى في أغلب الأحيان الإجابة نفسها التي تلقاها في استدعائه السابق. وهكذا يستنفد حد الطلبات المسموح له دون جدوى ويُرهق الخادم دون الحصول على معلومة جديدة.
تعرض هذه الصفحة الآليات التي تتيح تجنب هذه الاستدعاءات الزائدة، وحدود معدل الطلبات المطبقة على API.
تجنب جلب البيانات التي لم تتغير
تتضمن أغلب إجابات API في القراءة ترويسة ETag تحدد نسخة من الإجابة. احتفظوا بهذا المعرف مع البيانات المستلمة، وأرسلوه في الاستدعاء التالي ضمن الترويسة If-None-Match:
curl -i -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
إذا لم تتغير البيانات، يجيب Omniscol بالرمز 304 Not Modified دون محتوى. ويمكنكم حينئذ إعادة استخدام البيانات المحفوظة في الذاكرة المؤقتة. وفي الحالة المعاكسة، تتلقون إجابة 200 OK كاملة مرفقة بـ ETag جديد.
قيمة ETag قيمة معتمة: احتفظوا بها وأعيدوا إرسالها كما هي، بما فيها علامات الاقتباس والبادئة W/، دون محاولة بنائها أو فك رموزها. وهي خاصة بالطلب الذي أنتجها وبالوصول المستخدم: لا تعيدوا استخدامها مع عنوان URL آخر ولا مع رمز آخر.
تفيد الترويسة Cache-Control: private, no-cache بأن الإجابة يمكن حفظها في ذاكرة مؤقتة خاصة، لكن يجب التحقق من صلاحيتها لدى Omniscol قبل إعادة استخدامها. وهذا هو بالضبط دور If-None-Match.
بعض الإجابات لا تتضمن ETag، خصوصا عندما تتوقف على تاريخ اليوم ويمكن أن تتغير دون أي تعديل في بيانات الحساب. يجب جلب هذه الإجابات من جديد عند كل استدعاء.
بعد نشر إصدار جديد من Omniscol، تتجدد قيم ETag حتى لو لم تتغير البيانات. يتلقى الاستدعاء الأول حينئذ إجابة 200، ثم تستفيد الاستدعاءات اللاحقة من جديد من إجابات 304.
كما يقلل 304 المعالجة على جانب الخادم. ففي أغلب الحالات، عندما لا تتغير أي بيانات من الحساب منذ الاستدعاء الأخير، يمكن لـ Omniscol أن يجيب دون إعادة قراءة البيانات المعنية، ولا يُحتسب هذا الرمز 304 حينئذ ضمن الحد المرتبط بمفتاح API الخاص بكم. أما 304 الذي يُحصل عليه بعد إعادة قراءة البيانات فيُحتسب كإجابة عادية.
وهكذا يظل التحقق الدوري قليل الكلفة عندما لا تتغير البيانات. لكنه يظل خاضعا للحد العام لكل عنوان IP.
حفظ الإجابات في ذاكرة مؤقتة
إذا كان عدة مستخدمين أو عدة شاشات في تطبيقكم يطلعون على البيانات نفسها، فلا داعي للاستعلام من Omniscol لكل واحد منهم.
احتفظوا بالإجابات وقيم ETag الخاصة بها في ذاكرة مؤقتة للتطبيق تتحكمون فيها، مثل Redis أو Memcached أو جدول في قاعدة بيانات. يمكن لتطبيقكم عندئذ تقديم البيانات من هذه الذاكرة، على أن يتحقق من صلاحيتها لدى Omniscol باستخدام If-None-Match، على فترات منتظمة أو عندما ينبه Webhook إلى تعديل.
يجب أن يراعي مفتاح الذاكرة المؤقتة عنوان URL كاملا، والرمز المستخدم في المصادقة، وعند استخدامه، محتوى الطلب GET والترويسات التي تغير الإجابة مثل Accept-Language. قد يتيح رمزان بحقوق مختلفة الوصول إلى بيانات مختلفة: يجب ألا تُقدَّم إجابة حُصل عليها بأحدهما إلى مستخدم لا تتيح حقوقه الوصول إليها.
احتفظوا كذلك بمحتوى كل إجابة مع ETag الخاص بها. فمن دون البيانات المقابلة، لا تتيح إجابة 304 إعادة بناء النتيجة المنتظرة.
هذه الذاكرة المؤقتة للتطبيق مختلفة عن ذاكرة HTTP مؤقتة مشتركة: فالتوجيه Cache-Control: private يمنع هذه الأخيرة من حفظ الإجابات.
تلقي الإشعارات بدلا من الاستعلام الدوري
بدلا من التحقق دوريا من تغير البيانات، يمكنكم أن تطلبوا من Omniscol إشعار تطبيقكم عند حدوث تعديل.
تعتمد هذه الآلية على عمليات Webhook، التي تُضبط في شاشة تخصيص API (راجعوا تخصيص API). يمكن لـ Webhook أن يراقب نقطة وصول محددة أو حدثا مجمّعا يضم عدة تعديلات، مثل تعديل جدول زمني.
إبطال الذاكرة المؤقتة عند استلام Webhook
أبسط استخدام هو معاملة Webhook كإشارة إبطال.
عند وصول إشعار، يعلّم تطبيقكم البيانات المعنية بأنها منتهية الصلاحية ويتحقق منها من جديد لدى Omniscol. ليس من الضروري تفسير محتوى التعديل: فالـ Webhook يشير ببساطة إلى ضرورة تحقق جديد.
يتكامل هذا العمل بطبيعته مع الذاكرة المؤقتة الموصوفة سابقا.
مزامنة الحصص بالفروق
إذا كنتم تحتفظون بنسخة متزامنة من الحصص، فإن الخيار مع البيانات في حدث تعديل الجدول الزمني يتيح تلقي فروق تتضمن الحصص المضافة والمعدلة والمحذوفة.
يمكن لتطبيقكم حينئذ تطبيق هذه التغييرات وحدها، دون جلب الجدول الزمني بأكمله من جديد.
ضمان استلام الإشعارات
لا يجري Omniscol سوى محاولة إرسال واحدة لكل Webhook. وينتظر أربع ثوان على الأكثر، ولا يعيد المحاولة عند الفشل، ويسجل الفشل في سجلاته.
لذا يجب أن يؤكد خادمكم الاستلام بسرعة، بإجابة 200 OK أو 202 Accepted، ثم ينفذ المعالجة اللازمة بشكل غير متزامن.
احتفظوا كذلك بتحقق دوري كآلية تدارك. فإذا كان خادمكم غير متاح عند إرسال Webhook، سيتيح هذا التحقق اكتشاف التعديلات الفائتة. وبفضل إجابات 304، يظل قليل الكلفة عندما تكون البيانات محدّثة.
تأمين عمليات Webhook
للتحقق من أن الإشعار صادر فعلا عن Omniscol، اضبطوا ترويسة HTTP مخصصة تحتوي على سر لا يعرفه سوى تطبيقكم وOmniscol. يجب أن يرفض خادمكم الاستدعاءات التي لا تحمل القيمة المنتظرة.
توفر ترويستان إضافيتان معلومات عن سياق الإشعار:
X-Schoolيحدد حساب Omniscol المعني؛X-OS-authيحتوي على رمز مصادقة المستخدم الذي أجرى التعديل.
الرمز المرسل في X-OS-auth سري. لا تسجلوه في سجلاتكم، ولا ترسلوه إلى خدمات أخرى، وقيّدوا الوصول إليه بشدة.
طلب البيانات الضرورية فقط
الإجابة التي تحتوي على بيانات أقل تكون عادة أسرع إنتاجا ونقلا وحفظا في الذاكرة المؤقتة.
بالنسبة إلى الحصص، حدّدوا الفترة المطلوبة وصفّوا النتائج بحسب الكيانات التي تهمكم (راجعوا API الحصص).
بالنسبة إلى عمليات البحث، توفر نقطة الوصول search/query عوامل تصفية وإسقاطا للحقول وترقيما للصفحات (راجعوا الاستعلام المتقدم).
لتحديث عدد كبير من العناصر من النوع نفسه (الصفوف والقاعات والمواد وغيرها)، فضّلوا نقاط الوصول التي تتيح إرسال مجموعة كاملة في طلب واحد، عندما تكون متوفرة في وثائق OpenAPI، بدلا من تكرار الاستدعاءات الفردية.
احترام حدود معدل الطلبات
يُطبَّق حدّان لمعدل الطلبات على استدعاءات API. وعند بلوغ أحدهما، يجيب Omniscol بالرمز 429 Too Many Requests مرفقا بترويسة Retry-After تبين عدد الثواني التي يجب انتظارها قبل إعادة الطلب.
الحد لكل عنوان IP
الحد العام هو 300 طلب في كل نافذة مدتها 10 ثوان، لجميع نقاط الوصول في API، بما فيها MCP ولوحات العرض.
هذا الحد يكفي عموما لتكامل مصمم جيدا. لكن يمكن بلوغه بسبب حلقات استدعاء دون فواصل زمنية أو بسبب عدد مفرط من الطلبات المتوازية.
الحد لكل مفتاح API
تتقاسم الرموز الصادرة عن مفتاح API واحد حدّين:
- 60 طلبا في الدقيقة؛
- 5 000 طلب في اليوم.
يمكن أن تحمل الإجابات الترويسات التالية، التي تتيح متابعة الاستهلاك:
RateLimit-Policyيبين الحدود المطبقة، مثلا60;w=60, 5000;w=86400؛RateLimit-Limitيبين قيمة الحد الأقرب إلى البلوغ؛RateLimit-Remainingيبين عدد الطلبات التي ما زالت متاحة ضمن هذا الحد؛RateLimit-Resetيبين عدد الثواني قبل تجدّده.
هذه الترويسات غائبة خصوصا عن إجابات 304 التي يُحصل عليها دون إعادة قراءة البيانات: وغيابها لا يعني أن الحد قد استُنفد.
عندما يُستنفد الحد، تبين إجابة 429 أيضا مدة الانتظار في محتواها، عبر الحقل retry_after.
إجابات 304 التي يُحصل عليها دون إعادة قراءة البيانات لا تُحتسب ضمن هذين الحدين، لكنها تظل خاضعة للحد العام لكل عنوان IP.
إذا كانت هذه الحدود تعيق استخداما مشروعا لـ API، فتواصلوا معنا بدلا من تكثير المفاتيح.
معالجة الأخطاء وإعادة المحاولة
بعد إجابة 429
احترموا المدة التي تبينها Retry-After قبل إعادة الطلب. إعادة المحاولة فورا لا فائدة منها وقد تطيل الوضع، خصوصا إذا كانت عدة عمليات في تطبيقكم تعيد المحاولة في الوقت نفسه.
بعد خطأ في الخادم أو تجاوز المهلة
بعد خطأ 5xx أو تجاوز مهلة الانتظار، يمكن إعادة طلب قراءة بفاصل زمني متزايد بين المحاولات: ثانية واحدة، ثم ثانيتان، ثم أربع ثوان مثلا، حتى حد أقصى لعدد المحاولات.
أما بالنسبة إلى طلب كتابة، فالوضع مختلف: فقد يكون التعديل قد سُجّل حتى لو لم تصلكم الإجابة قط. تحققوا من الحالة الفعلية للبيانات قبل إعادة العملية، لتجنب التعديلات المكررة.
بعد إجابة 401
لا يمكن عموما حل إجابة 401 Unauthorized بمحاولة جديدة بالرمز نفسه. قد تشير خصوصا إلى أن الرمز منتهي الصلاحية، أو أن مفتاح API الخاص به حُذف أو انتهت صلاحيته، أو أن نقطة الوصول المطلوبة ليست ضمن ما يسمح به.
تحققوا من الرمز ومن الأذونات المرتبطة به قبل إعادة الاستدعاء (راجعوا API Omniscol).