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

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

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

حول واجهة Kahoot API 

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

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

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

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

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

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

تتم المصادقة على واجهة برمجة التطبيقات (API) من خلال استخدام رمز JWT من نوع «bearer»، والذي يجب تضمينه في رأس «Authentication» لكل طلب موجه إلى واجهة برمجة التطبيقات (API). تكون صلاحية الرموز محدودة بمدة ساعة واحدة، وبعدها يجب الحصول على رمز جديد.

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

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

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 . 

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

أمثلة على الأسئلة: 

{

"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. يحتاج المرء إلى التكرار على جميع الكتل (الأسئلة) التي تم تشغيلها، مع استبعاد الكتل التي لم تكن أسئلة على الإطلاق (المحتوى الملقب بـ الشرائح). 

يوضح المثال التالي إجابة على الجزء الثاني من لعبة «Kahoot»، والتي كانت عبارة عن اختبار اختيار واحد، حيث قام المشارك الذي يحمل المعرّف participantId=1234 (الاسم المستعار «جوني» كما هو موضح في مثال قائمة المشاركين) باختيار الخيار الثاني الذي تصادف أنه كان صحيحًا. يمكننا أن نلاحظ أيضاً أن المشارك الذي يحمل لقب "روبرت" لم يتمكن من الإجابة عن السؤال خلال الوقت المحدد.

{

"blockIndexInKahoot": 1

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

{

"participantId": 1234,

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

"الإجابة": {

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

"اختيار": 1,

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

"النقاط": 900

}، {،

}،

{

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

"answerStatus": "مهلة"

}،

}، ]

}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عرض بيانات واجهة برمجة التطبيقات (API)

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

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