دليل كاهوت! تقارير API

هل تتساءل عن كيفية استخدام Kahoot! تقارير API؟ إليك كل ما تحتاج إلى معرفته للبدء.

اختصارات

• حول واجهة Kahoot API
• كيفية الوصول إلى واجهة برمجة التطبيقات (API)
• المصادقة باستخدام واجهة برمجة التطبيقات (API)
• مسرد المصطلحات
• الطلبات الشائعة - الدليل الإرشادي

حول واجهة Kahoot API 

واجهة Kahoot API هي واجهة برمجة تطبيقات REST التي تتبع OpenAPI. يمكنك مراجعة جميع وثائق واجهة برمجة التطبيقات الخاصة بنا بما في ذلك تفاصيل الموارد ونقاط النهاية على https://results.kahoot.com/swagger/. 

من أجل إجراء مكالمات إلى واجهة برمجة التطبيقات Kahoot API، ستحتاج شركتك إلى وصول مصرح به. واجهة برمجة التطبيقات هي الأفضل للعملاء الذين لديهم فريق بيانات أو مطورين على دراية بواجهات برمجة التطبيقات. باستخدام واجهة برمجة التطبيقات هذه، ستتمكن شركتك من الوصول إلى جميع البيانات المدرجة أدناه خلال آخر 90 يومًا بعد انتهاء اللعبة. نحن نحدد توقيت بياناتنا وندعم تواريخ البدء والانتهاء عندما يسحب العميل البيانات من نظامنا. 

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

كيفية الوصول إلى واجهة برمجة التطبيقات (API)

لا يتوفر تفويض واجهة برمجة التطبيقات (API) إلا للعملاء في بعض الباقات ذات المستوى الأعلى. تواصل مع مدير نجاح العملاء إذا كنت مهتماً بالترقية أو بدء عملية التفويض.

المصادقة باستخدام واجهة برمجة التطبيقات (API)

يتم تحقيق المصادقة لواجهة برمجة التطبيقات من خلال استخدام رمز مميز لحامل JWT والذي يجب توفيره في رأس المصادقة لكل طلب لواجهة برمجة التطبيقات. الرموز محددة بوقت محدد بساعة يجب بعدها الحصول على رمز جديد.

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

فيما يلي مثال على طلب يمكن إجراؤه باستخدام تجعيد الشعر:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Authorization: أساسي <digest>" \
--عنوان "نوع المحتوى: تطبيق/x-www-form-urlencoded" \
- - بيانات المنح_نوع_البيانات=client_credentials

سيكون للرد من الطلب البنية التالية:

{
"access_token": "<رمز مميز لاستخدامه في طلبات واجهة برمجة التطبيقات>"،
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"النطاق": "ملف تعريف البريد الإلكتروني"
}

للمصادقة بشكل صحيح على واجهة برمجة التطبيقات، يجب عليك استخدام قيمة رمز الوصول في الرد أعلاه كرمز مميز لحامله في طلباتك إلى واجهة برمجة التطبيقات. هذا يعني أن رأس التخويل لجميع الطلبات يجب أن يكون له قيمة على شكل "حامل: <token>". إذا لم تقدم رمزًا مميزًا صالحًا بشكل صحيح إلى واجهة برمجة التطبيقات، فسيتم إرجاع الرد 401.

مسرد المصطلحات

الطلبات الشائعة - الدليل الإرشادي

• كيفية إدراج المشاركين في اللعبة
• من هو "المشارك"؟ 
• ابحث عن اللعبة
• ما هو الفرق بين معرف المشارك و معرف المستخدم? 
• كيفية الحصول على عنوان البريد الإلكتروني للمشارك
• كيفية سرد المشاركين الذين أجابوا على الأقل 80% من الأسئلة بشكل صحيح
• ماذا لو تم إرجاع 404؟ 
• مطابقة الإجابات مع المشاركين 
• ماذا تعني "الإجابة الصحيحة"؟
• العلاقة بين المهلة المحددة والإجابة الصحيحة

كيفية إدراج المشاركين في اللعبة

من هو "المشارك"؟ 

تصف الخطوات التالية كيفية إدراج جميع اللاعبين الذين دخلوا اللعبة. 

يرجى ملاحظة أن "الانضمام" ليس هو نفسه "اللعب بنشاط". من الممكن الانضمام إلى اللعبة وعدم الإجابة عن أي أسئلة بسبب مشاكل في الاتصال أو عدم الانتباه. سيستمر إدراج هؤلاء المشاركين في النتائج. 

ابحث عن اللعبة 

قم باستدعاء GET/GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} لسرد جميع الألعاب التي تم لعبها في مؤسستك في إطار زمني معين. أضفمعلمة استعلامالمؤشر في حالة توفر صفحة أخرى من النتائج والحاجة إليها.

سيحتوي نموذج الإخراج على قائمة بجلسات اللعب:

{
البيانات: [
"gameSessionId": "3c28c370-0407-0407-416f-a44f-087715b4ea89"، "hostUserId": "70feec9e-1ee3-4e35-8d6b-8d6b-0fe44d9f2358"، "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "الإصدار": 5 
}،
"وقت البدء": 1667928438123,
}
]،
المؤشر: "abcxyz"
} }

ابحث عن الجلسة في النتائج وتذكر أنها gameSessionId. 

قائمة المشاركين في اللعبة 

استدعاء GET /v1/organisations/{organisationId}/games/{gameSessionId}/المشاركون لسرد جميع المشاركين الذين انضموا إلى اللعبة.

نتيجة العينة: 

[

{

"participantId": 1234,

"الاسم المستعار": "جوني"،

"UserId": "f7e9a793-f223-4f2e-ad79-8bfa546a7180"

},

{

"معرف المشارك": "participantId": 4321,

"الاسم المستعار": "روبرت",

"UserId": "a9555f0c-68b2-41b1-a540-49c34e15242e"

}

]

ما الفرق بين معرف المشارك (participantId ) ومعرف المستخدم (userId)؟ 

• معرف المشارك هو عدد صحيح ويكون موجودًا دائمًا بغض النظر عن خيارات اللعبة.
• معرف المشارك يحدد لاعبًا معينًا في جلسة اللعب هذه فقط. قد يشير نفس المشارك في جلسة لعب مختلفة إلى شخص مختلف وعادةً ما يشير إلى شخص مختلف. 
• معرف المستخدم يتم تضمينه فقط في الألعاب مع تمكين خيار معرّف اللاعب. وذلك عندما يُطلب من اللاعبين تقديم بيانات اعتمادهم مثل البريد الإلكتروني بالإضافة إلى الاسم المستعار. أو عندما تتم دعوتهم إلى اللعبة باستخدام بريدهم الإلكتروني.
• معرف المستخدم يجعل من الممكن تتبع الشخص نفسه عبر جلسات لعب متعددة.

كيفية الحصول على عنوان البريد الإلكتروني للمشارك 

قم باستدعاء GET /v1/organisations/{organisationId}/ Users/{userId} سيحتوي الكائن الذي تم إرجاعه على خاصيةالبريد الإلكتروني . 

كيفية سرد المشاركين الذين أجابوا على الأقل 80% من الأسئلة بشكل صحيح 

ابحث عن اللعبة

راجع القسم الخاص بالعثور على اللعبة. 

ابحث عن المعلومات حول لعبة الكاهوت التي تم لعبها. يتكون من جزأين: 

1. المعرف - معرف UUID الذي يشير إلى الكاهوت الذي تم تشغيله

2. الإصدار - قد يكون قد تم تعديل الكاهوت من قبل المنشئ بعد إجراء اللعبة. في كل مرة يحدث ذلك يتم زيادة خاصية الإصدار. وهذا يضمن أن الإجابات تشير إلى البيانات الصحيحة. 

{ {

// بروبيرتيز أخرى

"kahootIdentifier": {

"id": "3c28c370-0407-416f-a44f-087715b4ea89",

"الإصدار": 5

},

}

احصل على مشاركين

انظر القسم الخاص بقائمة المشاركين.

الحصول على بيانات كاهوت 

قم باستدعاء GET/GET /v1/organisations/{organisationId}/kahoots/{kahootId}/ الإصدارات/{version} للحصول على kahoot مع معلمات الاستعلام استنادًا إلى خصائصkahootIdentifier.id و kahootIdentifier.version . 

ستحتوي النتيجة على جميع الأسئلة (الكتل) التي يتضمنها اختبار kahoot إلى جانب خيارات الإجابة التي كانت متاحة للمشاركين إن وجدت. ستتم الإشارة إلى الأسئلة وخيارات الإجابة في وقت لاحق من خلال مستندات الإجابة. 

عينة من الأسئلة: 

{

"kahootIdentifier": {

"id": "3c28c370-0407-416f-a44f-087715b4ea89",

"الإصدار": 5

}،

"العنوان": "عنوان كاهوت"،

"الوصف": "يدور هذا الكاهوت حول ..."،

"الأسئلة": [

{

"نوع المحتوى": "المحتوى"

"blockIndex": 0

"العنوان": "هذا هو العرض التقديمي للشركة"

"الوصف": "بعض محتويات الشرائح"

}،

{ {

"نوع المحتوى": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"السؤال": "من هو أكبر عميل لدينا؟" 

 "الاختيارات": [

{"answerText": "شركة Very Big Corp. of America"، "صحيح": خطأ}،

{"answerText": "Skynet"، "صحيح": صواب}

]

}،

] ]

}

احصل على جميع الإجابات 

قم باستدعاء GET/GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers باستخدام gameSessi onId الذي تم الحصول عليه عند البحث عن اللعبة (انظر قسم البحث عن اللعبة) و blockIndex كونه فهرس السؤال في kahoot. يحتاج المرء إلى التكرار على جميع الكتل (الأسئلة) التي تم تشغيلها، مع استبعاد الكتل التي لم تكن أسئلة على الإطلاق (المحتوى الملقب بـ الشرائح). 

يُظهر المثال التالي إجابة للكتلة الثانية من الكاهوت التي كانت عبارة عن اختبار اختيار واحد، حيث قام المشارك بتحديد إجابة المشارك بـ parti cipantId=1234 (الاسم المستعار "جوني" كما في مثال المشاركين في القائمة) واختار الخيار الثاني الذي صادف أنه صحيح. يمكننا أن نلاحظ أيضاً أن المشارك الذي يحمل لقب "روبرت" لم يتمكن من الإجابة عن السؤال خلال الوقت المحدد.

{

"blockIndexInKahoot": 1

"الإجابات": [

{

"participantId": 1234,

"answerStatus": "تم الاستلام"،

"الإجابة": {

"النوع": "SINGLE_SELECT_QUIZ",

"اختيار": 1,

"صحيح": صحيح،

"النقاط": 900

}، {،

}،

{

"معرف المشارك": 4321,

"answerStatus": "مهلة"

}،

}، ]

}

من أجل معرفة ما كان الاختيار وما كان لقب المشارك يحتاج المرء إلى الرجوع إلى بيانات كاهوت ذات الصلة وبيانات المشارك المذكورة في الأقسام السابقة. 

ماذا لو تم إرجاع 404؟ 

يمكن أن تكون إجابات كتلة معينة مفقودة في الحالات التالية: 

1. السؤال المعطى (الكتلة) من النوع المحتوى. "الإجابة" عليها ليست واضحة المعالم. 
2. تم لعب اللعبة كواجب ولم يصل أي من المشاركين إلى هذا السؤال 3. 
3. حدثت مشكلة في الشبكة أثناء اللعب ولم يتم حفظ الإجابة (حالة نادرة، ولكن من الممكن أن تحدث).

على أي حال، يجب أن يكون العملاء مستعدين لأن بيانات الإجابة قد تكون مفقودة هناك. 

مطابقة الإجابات مع المشاركين 

تحتوي الإجابات فقط على الروابط الخاصة بالمشاركين الذين تم تضمين تفاصيلهم في حمولة استجابة نقطة النهاية المنفصلة (راجع قسم "قائمة المشاركين في اللعبة"). هذا الرابط هو خاصيةمعرف المشارك الموجودة في كلا الحمولتين. 

ماذا تعني "الإجابة الصحيحة"؟ 

في حالة بعض أنواع الأسئلة، توجد منطقة رمادية بين حالة الإجابة "غير صحيحة" و"صحيحة".

أسئلة الاختبار متعدد التحديد 

صحيح - اختار المشارك جميع الاختيارات الصحيحة ولم يختر أيًا من الاختيارات الخاطئة

جزئيًا_صحيح - اختار المشارك خيارًا واحدًا على الأقل من الخيارات الصحيحة ولم يختر أيًا من الخيارات الخاطئة خاطئ - اختار المشارك خيارًا واحدًا على الأقل من الخيارات الخاطئة

أسئلة المنزلق 

صحيح - اختار المشارك القيمة الصحيحة على شريط التمرير

ALMOST_CORRECT - اختار المشارك قيمة لم تكن دقيقة، ولكن في حدود التفاوت المسموح به الذي حدده منشئ kahoot خطأ - كانت القيمة المحددة خارج نطاق التفاوت المسموح به

جميع الأسئلة الأخرى 

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

العلاقة بين المهلة المحددة والإجابة الصحيحة 

لن تحتوي كائنات ParticipantAnswer ذات الحالة التي تساوي TIMEOUT على خاصيةالإجابة ، لذا فهي ليست "صحيحة" ولا "خاطئة".  الأمر متروك للمستخدم ليقرر كيفية التعامل معها. ودائماً ما يتم تخصيص نقاط صفر لهم أثناء المباراة.

تقديم بيانات API.

هناك العديد من الطرق لتقديم بيانات API المستخرجة. إليك مثال على لعبة Kahoot! البيانات المرئية في Power BI.

💡 هل وجدت هذا مفيداً؟ اشترك في قناتنا على Youtube للحصول على المزيد من النصائح و Kahoot! دروس تعليمية!