الانتقال من الواجهة القديمة

ما الذي تغير

الواجهة القديمة كانت تستخدم:

• Header: X-TOKEN-KEY
• Routes: /api/open/evaluation/*

الواجهة الحالية تستخدم:

• Header: X-API-Key
• Routes: /api/keath/public/v1/*

التحويل

الفكرة الجديدة

في السابق كنت ترسل النص والrubrics مباشرة.

الآن اختر أحد مسارين:

1. مسار assignment:

   • احصل على model_id
   • أنشئ assignment
   • قيّم باستخدام assignment_id

2. مسار one-pass:

   • احصل على model_id
   • أرسل النموذج والسؤال والrubric وإجابة الطالب في طلب واحد

التقييم غير المتزامن الموثوق

يرجع POST /evaluations/one-pass وPOST /evaluations/batch استجابة HTTP 202 Accepted مع task_id عام. أرسل Idempotency-Key حتى يعيد تكرار طلب الشبكة نفسه المهمة نفسها بدلا من إنشاء مهمة مكررة. يقبل batch من 1 إلى 100 عنصر.

تمر المهمة بالمراحل QUEUED وUPLOADING وSUBMITTED وPROGRESS، ثم تنتهي بSUCCESS أو FAILURE أو CANCEL. لا تخصم credits إلا بعد التحقق من نتيجة مكتملة. استخدم polling بمهلة نهائية وbackoff.

للتوافق، يحتفظ POST /evaluations مع assignment موجود بالمسار القديم: يبدأ عادة بPENDING وتخصم credits عند قبول المهمة. لذلك لا تطبق حالته الأولى أو توقيت الخصم على one-pass أو batch.

ما يجب تغييره في العميل

1. استبدل X-TOKEN-KEY ب X-API-Key.
2. استبدل /api/open/evaluation/* ب /api/keath/public/v1/*.
3. لا تستخدم model_id مكان assignment_id.
4. استخدم POST /evaluations إذا كان لديك assignment.
5. استخدم POST /evaluations/one-pass إذا كنت لا تريد إنشاء assignment.
6. تابع الحالة عبر GET /evaluations/:taskId/status.
7. اقرأ النتيجة النهائية عبر GET /evaluations/:taskId.

الصيغ المدعومة

الواجهة الجديدة تقبل إجابات الطلاب كنص أو ملف:

• PDF
• صور
• DOCX
• TXT
• RTF

بالنسبة إلى Google Docs، صدّر المستند أولا إلى DOCX أو PDF أو نص. الاستيراد المباشر عبر Google Docs OAuth غير موجود في public v1.

اختبار قبل النقل

قبل تحويل الطلبات الحقيقية:

• تأكد أن GET /credits يعمل.
• تأكد أن GET /models يعرض النموذج المطلوب.
• تأكد أن POST /assignments يرجع assignment_id.
• تأكد أن POST /evaluations يرجع task_id.
• تأكد أن polling ينتهي ب SUCCESS أو FAILURE أو CANCEL.
• تأكد أن الكود لم يعد يحتوي على X-TOKEN-KEY.