Reporting API Endpoints

نقاط النهاية المضمنة في API لإعداد التقارير هي نقاط نهاية خاصة لا تأتي مع سياسة إيقاف في الوقت الحالي. قد تغير Anthology Ally نقاط النهاية هذه أو تحدثها بناءً على خارطة الطريق أو الإصدارات المستقبلية لدينا.

اطَّلع على الوثائق الفنية التالية للتعرف على كيفية إعداد نقاط النهاية وتخصيصها بشكل مناسب. لا تتردد في الاطلاع على كيفية تكامل API الخاصة بـ Ally مع أداة إعداد التقارير الخارجية للحصول على إرشادات إضافية. 

الأساليب المتاحة

هناك أسلوبان متاحان لـ Ally API لإعداد التقارير. يصفهما القسم التالي: 

استبدل [Ally Client ID] بمعرّف Ally الخاص بك. إذا كنت لا تعلم المعرِّف الخاص بك، فإنه يمكنك إنشاء تذكرة دعم لطلبها.

استبدل [Region] استنادًا إلى المنطقة المستضاف فيها بيئة Ally الخاصة بمؤسستك:

• مركز بيانات الولايات المتحدة: prod.ally.ac
• مركز البيانات الكندي: prod-ca-central-1.ally.ac
• مركز البيانات الأوروبي: prod-eu-central-1.ally.ac
• مركز البيانات السنغافوري: prod-ap-southeast-1.ally.ac
• مركز البيانات الأسترالي: prod-ap-southeast-2.ally.ac

قد تختلف المعلومات الواردة أعلاه حسب نظام إدارة التعلم (LMS). يمكنك مراجعة تعريف العمود في "وثائق تقرير المقرر الدراسي" لكل نظام إدارة تعلم:

• Blackboard Learn
• Moodle
• D2L Brightspace
• Instructure Canvas

استجابة حالة HTTP  

تشتمل Ally API على حقل للحالة في بيانات التعريف كما يلي:

• الحالة 200 - نجاح: تم استلام طلبك بنجاح ومجموعة البيانات المطلوبة تمثل جزءًا من الاستجابة. 
• الحالة 202 - جارٍ المعالجة: تم استلام طلبك بنجاح لكن مجموعة البيانات قيد الإعداد، وليست متاحة حتى الآن. كرر طلبك بعد مرور بعض الوقت (يُوصى بدقيقة واحدة على الأقل).
• الحالة 401 - غير مصرح به: معرّف عميل Ally أو الرمز المميز للتفويض غير صحيحين.
• الحالة 400 - طلب غير صالح: يحتوي عنوان URL على اسم معلمة غير صالح، على سبيل المثال، خيار عامل تصفية أو قيمة أو مُعامِل غير معروف. راجع بناء جملة URL. تذكر أن بعض خيارات التصفية والفرز حساسة لحالة الأحرف. 

توثيق الأساليب 

الأسلوب: شامل  

طلب HTML: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall 

استبدل [Ally Client ID] بمعرّف Ally الخاص بك. إذا كنت لا تعرف المعرِّف الخاص بك، يمكنك إنشاء تذكرة دعم لطلبه. 

استبدل [Region] استنادًا إلى المنطقة المستضاف فيها بيئة Ally الخاصة بمؤسستك:

• مركز بيانات الولايات المتحدة: prod.ally.ac
• مركز البيانات الكندي: prod-ca-central-1.ally.ac
• مركز البيانات الأوروبي: prod-eu-central-1.ally.ac
• مركز البيانات السنغافوري: prod-ap-southeast-1.ally.ac
• مركز البيانات الأسترالي: prod-ap-southeast-2.ally.ac

التفويض: الرمز المميز لحامل OAuth 

المعلمات: خيارات فرز أو عوامل تصفية اختيارية. 

نص الطلب: لا يوجد 

الاستجابة: 

{ 
    "البيانات": [ 
        { 
            "application/x-quiz": 2, 
            "observedDeletedOn": "", 
            "termName": "خريف 2016", 
            "courseId": "1", 
            "application/x-announcement": 0, 
            "image": 4, 
            "termId": "2", 
            "document": 93, 
            "allyEnabled":صواب, 
            "pdf": 74, 
            "courseCode": "BIO101", 
            "application/x-assignment": 0, 
            "departmentId": "1", 
            "totalFiles": 192, 
            "courseUrl": "https://ally.instructure.com/courses/1", 
            "departmentName": "Anthology Ally", 
            "application/x-page": 1, 
            "filesScore": 0.6022810739019293, 
            "application/x-syllabus": 1, 
            "numberOfStudents": 1, 
            "html-page": 5, 
            "lastCheckedOn": "2022-04-13 15:33:23", 
            "WYSIWYGScore": 1.0, 
            "totalWYSIWYG": 5, 
            "courseName": "Biology 101", 
            "application/x-discussion-topic": 1, 
            "other": 11, 
            "overallScore": 0.6129724428830603, 
            "presentation": 5 
        } 
], 
    "metadata": {
    "filteredTotal": 0,
    "الإجمالي": 7186,
        "to": 7186,
    "status": "جارٍ المعالجة", 
        "from":1 
    } 
} 

الأسلوب: المشكلات 

طلب HTTP: GET 
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall 

استبدل [Ally Client ID] ID بمعرّف Ally الخاص بك. إذا كنت لا تعرف المعرِّف الخاص بك، يمكنك إنشاء تذكرة دعم لطلبه. 

استبدل [Region] استنادًا إلى المنطقة المستضاف فيها بيئة Ally الخاصة بمؤسستك:

• مركز بيانات الولايات المتحدة: prod.ally.ac
• مركز البيانات الكندي: prod-ca-central-1.ally.ac
• مركز البيانات الأوروبي: prod-eu-central-1.ally.ac
• مركز البيانات السنغافوري: prod-ap-southeast-1.ally.ac
• مركز البيانات الأسترالي: prod-ap-southeast-2.ally.ac

التفويض: الرمز المميز لحامل OAuth  

المعلمات: خيارات فرز أو عوامل تصفية اختيارية. 

النص الأساسي للطلب: لا يوجد 

الاستجابة: 

{ 
    "البيانات": [ 
        { 
            "imageDecorative2": 4, 
            "htmlEmptyHeading2": 0, 
            "imageSeizure1": 2, 
            "observedDeletedOn": "", 
            "htmlObjectAlt2": 0, 
            "security1": 3, 
            "termName": "خريف 2016", 
            "courseId": "1", 
            "languageCorrect3": 14, 
            "htmlColorContrast2": 2, 
            "htmlLinkName3": 0, 
            "termId": "2", 
            "languagePresence3": 10, 
            "allyEnabled": صواب, 
            "htmlLabel2": 0, 
            "alternativeText2":68, 
            "htmlImageAlt2":0, 
            "htmlImageRedundantAlt3":0, 
            "headingsPresence2": 20, 
            "courseCode": "BIO101", 
            "headingsSequential3": 4, 
            "departmentId": "1", 
            "htmlHeadingsPresence2": 0, 
            "courseUrl": "https://ally.instructure.com/courses/1", 
            "headingsStartAtOne3": 4, 
            "departmentName": "Anthology Ally", 
            "htmlHeadingsStart2":0, 
            "htmlTdHasHeader2":0, 
            "htmlList3":0, 
            "htmlDefinitionList3":0, 
            "htmlCaption2":0, 
            "tableHeaders2":23, 
            "htmlEmptyTableHeader2":0, 
            "htmlHasLang3":1, 
            "ocred2":0, 
            "scanned1":6, 
            "htmlBrokenLink2": 0, 
            "عدد الطلاب":1, 
            "htmlHeadingOrder3": 0, 
            "lastCheckedOn": "2022-04-13 15:33:23", 
            "headingsHigherLevel3":0, 
            "contrast2":28, 
            "title3":46, 
            "imageOcr3":0, 
            "tagged2": 4, 
            "libraryReference":172, 
            "courseName": "Biology 101", 
            "imageContrast2": 0, 
            "imageDescription2": 4, 
            "htmlTitle3": 1, 
            "parsable1":2 
        } 
], 
    "metadata": { 
        "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "جارٍ المعالجة", 
        "from": 1 
    } 
} 

حيث: 

• البيانات: يحتوي على مجموعة بيانات النتائج. 
• بيانات تعريف: 
  • إلى: السجل الذي سيتم إحضار البيانات إليه، يكون "الإزاحة" + "الحد" أو "الإجمالي" إذا كان المجموع يتجاوز "الإجمالي". 
  • من: السجل الذي ستبدأ منه البيانات، يكون "الإزاحة" + 1. 
  • الإجمالي: إجمالي عدد المقررات الدراسية التي تأخذها Ally في الاعتبار في مثيل LMS. 

الإزاحة - التي يبدأ منها السجل 

• الصف الأول يكون: الإزاحة = 0، 
• إذا كانت (الإزاحة < 0)، فسيتلقى المستخدم حينها الخطأ 400 - [قيمة غير صالحة (المعلمة = الإزاحة، الرسالة = لا توجد مثل هذه البيانات)]، 
• عندما تكون (الإزاحة >= الإجمالي) =>، فسيتلقى المستخدم حينها الخطأ 400 - [قيمة غير صالحة (المعلمة = الإزاحة، الرسالة = لا توجد مثل هذه البيانات)] 

الحد - عدد السجلات التي يتم استردادها بدءًا من الإزاحة 

• إذا كان (الحد < 1)، فسيتلقى المستخدم إذًا الخطأ 400 - [قيمة غير صالحة (المعلمة = الحد، الرسالة = الحد خارج الحدود)]
• إذا كان (الحد > 10000)، فسيتلقى المستخدم حينها الخطأ 400 - [قيمة غير صالحة (المعلمة = الحد، الرسالة = الحد خارج الحدود)] 
• إذا كانت (الإزاحة < الإجمالي && الإزاحة + الحد > الإجمالي)، فسنغير حينها الحد في الخلفية من أجلك، وسيتم استرداد البيانات حتى النهاية (الإجمالي) 

عوامل التصفية وخيارات الفرز 

يمكن تصفية استجابات نقطة النهاية في عنوان URL. يصف هذا القسم الخيارات المتاحة. 

خيارات الفرز 

يمكنك تحديد ما إذا كنت تريد عرض النتائج التي تم فرزها بترتيب تصاعدي أو تنازلي مع مراعاة معيار واحد. إذا كنت بحاجة إلى إضافة خيار فرز، فإنه يجب عليك إضافة معلمة الفرز كما هو موضح أدناه:

endpoint-url?sort=<Sort parameter value> 

حيث <Sort parameter value> يمكن أن تكون أيًا من قيم المعلمات التالية: 

قيم المعلمات حساسة لحالة الحروف، ويمكن استخدام خيار فرز واحد فحسب في كل مرة. 

بشكل افتراضي، يتم فرز النتائج حسب الترتيب التصاعدي. إذا كنت تريد تعيين ترتيب مختلف، يمكنك إضافة معلمة الترتيب: 

endpoint-url?sort=<Sort parameter value>&order=<Order value> 

حيث <قيمة الطلب> يمكن أن تكون: تصاعدي أو تنازلي 

مثال: 

https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc 

خيارات التصفية 

يمكنك استخدام خيارات التصفية للحصول على استجابات أصغر أو أقل بناءً على المعايير المحددة.  وإذا كنت بحاجة إلى إضافة خيار تصفية، يجب عليك إضافة معلمة التصفية على النحو الموضح أدناه:

معلمات التصفية (بلا مُعامِل) 

 endpoint-url?<Filter Parameter>=<value> 

معلمات عامل التصفية (مع وجود مُعامِل) 

endpoint-url?<Filter Parameter>=<Operator>:<value> 

حيث: 

• <معلمة عامل التصفية>: تصفية المعلمة للحصول على مجموعة أصغر من النتائج. يمكنك الرجوع إلى المعلمات المدعومة في الجدول الوارد أدناه. 
• <العامل>: يجب عليك استخدام مُعامِل من أجل التصفية، مثل "equal" (يساوي") أو "not equal" (لا يساوي). 
• <القيمة>: القيمة المستخدمة في عامل التصفية. 

تُعد قيم المعلمات حساسة لحالة الحروف.

العوامل المدعومة

يحتوي الجدول التالي على المُعامِلات المدعومة استنادًا إلى نوع الحقل: 

مثال: 

يسترد المثال التالي جميع المقررات الدراسية التي تحتوي على الكلمة الأساسية "اختبارات" في اسم المقرر الدراسي:

https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests 

استخدام عوامل تصفية متعددة 

يمكنك دمج خيارات الفرز والتصفية في عنوان URL لنقطة النهاية نفسه عن طريق إضافة الحرف "&" بين الشرطين. على سبيل المثال، لنفترض أنك تريد استرداد جميع المقررات الدراسية التي تحتوي على الكلمة الأساسية "اختبار" في اسم المقرر الدراسي حيث تكون Ally قيد التمكين، وتكون درجتها الإجمالية أقل من 90%. سيبدو عنوان URL على النحو التالي:

https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9

يمكنك أيضًا استخدام خيارين للتصفية. على سبيل المثال، لنفترض أنك بحاجة إلى الحصول على جميع المقررات الدراسية التي تحتوي على درجة إجمالية تتراوح بين 10% و70%:

https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7