คู่มือการใช้ Kahoot! รายงาน API

สงสัยว่าจะใช้ Kahoot! อย่างไร รายงาน API? นี่คือทุกสิ่งที่คุณจำเป็นต้องรู้เพื่อเริ่มต้น

ทางลัด:

• เกี่ยวกับ Kahoot API
• วิธีการเข้าถึง API
• การตรวจสอบสิทธิ์ด้วย API
• คำศัพท์
• คำขอทั่วไป - คำแนะนำ

เกี่ยวกับ Kahoot API 

Kahoot API เป็น REST API ที่ปฏิบัติตาม OpenAPI คุณสามารถตรวจสอบเอกสาร API ทั้งหมดของเรา รวมถึงรายละเอียดของทรัพยากรและจุดสิ้นสุดได้ที่ https://results.kahoot.com/swagger/. 

เพื่อที่จะโทรไปยัง Kahoot API บริษัทของคุณจะต้องได้รับสิทธิ์การเข้าถึงที่ได้รับอนุญาต API เหมาะที่สุดสำหรับลูกค้าที่มีทีมงานข้อมูลหรือผู้พัฒนาที่คุ้นเคยกับ API ด้วย API นี้ บริษัทของคุณจะสามารถเข้าถึงข้อมูลทั้งหมดที่ระบุไว้ด้านล่างได้ภายใน 90 วันหลังเกมสิ้นสุดลง เราประทับเวลาข้อมูลของเราและรองรับวันที่เริ่มต้นและสิ้นสุดเมื่อลูกค้าดึงข้อมูลจากระบบของเรา 

API ของ Kahoot รายงานข้อมูลที่เกี่ยวข้องกับเกม ผู้ใช้ ผู้เข้าร่วม องค์กร และ Kahoot ที่สร้างโดยองค์กร บางครั้งการรายงานของเราบนแพลตฟอร์มสามารถทำได้เพียงเท่านั้น สำหรับลูกค้าที่ใช้ผลิตภัณฑ์บ่อยครั้งหรือมีผู้เข้าร่วมจำนวนมาก และต้องการติดตามกิจกรรมของพวกเขา API เป็นวิธีที่ยอดเยี่ยมในการดำเนินการดังกล่าวอย่างปรับขนาดได้

วิธีการเข้าถึง API

การอนุญาตใช้งาน API นั้นมีให้เฉพาะกับลูกค้าที่ใช้แผนระดับสูงสุดบางแผนเท่านั้น ติดต่อผู้จัดการความสำเร็จของลูกค้าของคุณหากคุณสนใจในการอัปเกรดหรือเริ่มกระบวนการอนุญาต

การตรวจสอบสิทธิ์ด้วย API

การตรวจสอบสิทธิ์สำหรับ API จะทำได้โดยการใช้โทเค็นผู้ถือ JWT ซึ่งควรระบุไว้ในส่วนหัวการตรวจสอบสิทธิ์ของแต่ละคำขอไปยัง API โทเค็นมีระยะเวลาจำกัดเพียงหนึ่งชั่วโมง หลังจากนั้นจะต้องรับโทเค็นใหม่

หากต้องการรับโทเค็น ก่อนอื่นคุณต้องมีรหัสลูกค้าและความลับ ซึ่งผู้จัดการความสำเร็จของลูกค้าจะเป็นผู้จัดเตรียมให้ เมื่อคุณมีข้อมูลประจำตัวเหล่านี้แล้ว คุณต้องขอโทเค็นจากเซิร์ฟเวอร์การตรวจสอบสิทธิ์ของเราตามที่อธิบายไว้ด้านล่าง

ตัวอย่างคำขอที่สามารถทำโดยใช้ curl แสดงด้านล่างนี้:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Authorization: Basic <digest>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

การตอบสนองจากคำร้องขอจะมีโครงสร้างดังต่อไปนี้:

{
"access_token": "<token to use in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

หากต้องการพิสูจน์ตัวตนกับ API อย่างถูกต้อง คุณต้องใช้ค่าของ access_token ในการตอบสนองข้างต้นเป็นโทเค็นผู้ถือในการร้องขอไปยัง API ซึ่งหมายความว่าส่วนหัวการอนุญาตของคำขอทั้งหมดควรมีค่าในรูปแบบ “Bearer: <token>” หากคุณไม่ได้ระบุโทเค็นที่ถูกต้องให้กับ API อย่างถูกต้อง จะมีการส่งคืนการตอบสนอง 401

คำศัพท์

คำขอทั่วไป - คำแนะนำ

• วิธีการแสดงรายชื่อผู้เข้าร่วมเกม
• “ผู้เข้าร่วม” คือใคร? 
• ค้นหาเกม
• ความแตกต่างระหว่าง ผู้เข้าร่วมId และ รหัสผู้ใช้อะไร? 
• วิธีการรับที่อยู่อีเมลของผู้เข้าร่วม
• วิธีการแสดงรายชื่อผู้เข้าร่วมที่ตอบคำถามถูกอย่างน้อย 80%
• จะเกิดอะไรขึ้นถ้าเกิดข้อผิดพลาด 404 ขึ้น? 
• การจับคู่คำตอบกับผู้เข้าร่วม 
• “คำตอบที่ถูกต้อง” หมายถึงอะไร
• ความสัมพันธ์ระหว่างคำตอบที่ถูกต้องกับเวลาที่หมดอายุ

วิธีการแสดงรายชื่อผู้เข้าร่วมเกม

“ผู้เข้าร่วม” คือใคร? 

ขั้นตอนต่อไปนี้อธิบายวิธีการแสดงรายชื่อผู้เล่นทั้งหมดที่เข้าสู่เกม 

โปรดทราบว่า “การเข้าร่วม” ไม่เหมือนกับ “การเล่นอย่างจริงจัง” คุณอาจเข้าร่วมเกมและไม่ต้องตอบคำถามใดๆ เนื่องมาจากปัญหาการเชื่อมต่อหรือไม่ได้ใส่ใจ ผู้เข้าร่วมดังกล่าวจะยังคงรวมอยู่ในผลลัพธ์ 

ค้นหาเกม 

เรียกใช้ GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} เพื่อแสดงรายการเกมทั้งหมดที่เล่นในองค์กรของคุณในช่วงเวลาที่กำหนด เพิ่มเคอร์เซอร์ พารามิเตอร์คิวรีในกรณีที่มีหน้าผลลัพธ์อื่นและจำเป็น

ตัวอย่างผลลัพธ์จะประกอบด้วยรายการของเซสชันเกม:

{
ข้อมูล: [
"gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358",  "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version": 5 
},
"startTime": 1667928438123,
}
],
เคอร์เซอร์: "abcxyz"
}

ค้นหาเซสชันในผลลัพธ์ และจำไว้ว่าเป็น gameSessionId. 

รายชื่อผู้เข้าร่วมกิจกรรมเกม 

เรียก GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants เพื่อแสดงรายการผู้เข้าร่วมทั้งหมดที่เข้าร่วมเกม

ตัวอย่างผลลัพธ์: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

ความแตกต่างระหว่าง participantId และ userIdคืออะไร? 

• participantId เป็นจำนวนเต็มและมีอยู่เสมอไม่ว่าจะมีตัวเลือกเกมใดก็ตาม
• participantId ระบุผู้เล่นที่กำหนดไว้ภายในเซสชันเกมนี้เท่านั้น เหมือนกัน participantId ในเซสชั่นเกมที่แตกต่างกัน อาจและโดยปกติจะหมายถึงบุคคลอื่น 
• userId จะมีอยู่ในเกมที่มีการเปิดใช้งานตัวเลือก Player Identifier เท่านั้น นั่นเป็นเวลาที่ผู้เล่นจะถูกขอให้ระบุข้อมูลประจำตัว เช่น อีเมล นอกเหนือไปจากชื่อเล่น หรือเมื่อพวกเขาได้รับเชิญเข้าร่วมเกมโดยใช้อีเมลของพวกเขา
• userId ทำให้สามารถติดตามบุคคลเดียวกันได้ในหลายเซสชั่นเกม

วิธีการรับที่อยู่อีเมลของผู้เข้าร่วม 

เรียกใช้ GET /v1/organisations/{organisationId}/users/{userId} อ็อบเจ็กต์ที่ส่งคืนจะมีคุณสมบัติ email  

วิธีการแสดงรายชื่อผู้เข้าร่วมที่ตอบคำถามถูกอย่างน้อย 80% 

ค้นหาเกม

ดูส่วนเกี่ยวกับการค้นหาเกม. 

ค้นหาข้อมูลเกี่ยวกับ kahoot ที่ถูกเล่น มีสองส่วน: 

1. id - UUID อ้างอิงถึง kahoot ที่ถูกเล่น

2. เวอร์ชัน - Kahoot อาจได้รับการแก้ไขโดยผู้สร้างหลังจากเกมเกิดขึ้น ทุกครั้งที่เกิดเหตุการณ์ดังกล่าว คุณสมบัติเวอร์ชันจะเพิ่มขึ้น วิธีนี้จะช่วยให้แน่ใจว่าคำตอบจะอ้างอิงถึงข้อมูลที่ถูกต้อง 

{

// คุณสมบัติอื่น ๆ

"kahootIdentifier": {

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

"version": 5

},

}

รับผู้เข้าร่วม

ดูส่วนการแสดงรายชื่อผู้เข้าร่วม.

รับข้อมูล kahoot 

เรียกใช้ GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} เพื่อรับ kahoot พร้อมพารามิเตอร์แบบสอบถามที่อิงตามคุณสมบัติ kahootIdentifier.id และ kahootIdentifier.version  

ผลลัพธ์จะประกอบด้วยคำถามทั้งหมด (บล็อค) ที่มีอยู่ใน Kahoot พร้อมตัวเลือกคำตอบที่ผู้เข้าร่วมสามารถเลือกได้หากมี คำถามและตัวเลือกคำตอบจะมีการอ้างอิงในเอกสารคำตอบในภายหลัง 

คำถามตัวอย่าง: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description":"kahoot นี้เกี่ยวกับ ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "นี่คือการนำเสนอของบริษัท"

"description":"เนื้อหาสไลด์บางส่วน"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "ลูกค้าใหญ่ที่สุดของเราคือใคร?" 

 "choices": [

{"answerText": "Very Big Corp. of America", "correct":  false},

{"answerText": "Skynet", "correct": true}

]

},

]

}

รับคำตอบทั้งหมด 

เรียกใช้ GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers โดยใช้ gameSessi onId ที่ได้รับเมื่อค้นหาเกม (ดูส่วนค้นหาเกม) และ blockIndex โดยเป็นดัชนีของคำถามใน kahoot จำเป็นต้องทำซ้ำในทุกบล็อก (คำถาม) ที่ถูกเล่น โดยไม่รวมบล็อกที่ไม่ใช่คำถามเลย (เนื้อหา หรือที่เรียกว่า... สไลด์) 

ตัวอย่างต่อไปนี้แสดงคำตอบสำหรับบล็อกที่สองของ kahoot ซึ่งเป็นแบบทดสอบแบบเลือกรายการเดียว โดยผู้เข้าร่วมระบุด้วย parti cipantId=1234 (ชื่อเล่น "Johnny" เช่นเดียวกับในตัวอย่างการแสดงรายชื่อผู้เข้าร่วม ) และเลือกตัวเลือกที่สองซึ่งบังเอิญถูกต้อง เราจะเห็นได้ว่าผู้เข้าร่วมที่มีชื่อเล่นว่า “โรเบิร์ต” ไม่สามารถตอบคำถามได้ภายในเวลาที่กำหนด

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus":"RECEIVED",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

เพื่อทราบว่าตัวเลือกคืออะไรและชื่อเล่นของผู้เข้าร่วมคืออะไร จำเป็นต้องอ้างอิงข้อมูล kahoot ที่เกี่ยวข้อง และข้อมูลของผู้เข้าร่วม ที่กล่าวถึงในหัวข้อก่อนหน้า 

จะเกิดอะไรขึ้นถ้าเกิดข้อผิดพลาด 404 ขึ้น? 

คำตอบสำหรับบล็อกที่กำหนดอาจหายไปในกรณีต่อไปนี้: 

1. คำถามที่กำหนด (บล็อค) เป็นประเภท CONTENT. การ “ตอบ” พวกเขานั้นไม่ชัดเจนนัก 
2. เกมนี้เล่นโดยเป็นการมอบหมายงาน และไม่มีผู้เข้าร่วมคนใดทำได้ถึงคำถามข้อ 3 
3. มีปัญหากับเครือข่ายระหว่างการเล่นเกม และคำตอบไม่ได้รับการบันทึก (เป็นกรณีที่เกิดขึ้นได้ยาก แต่ก็อาจเกิดขึ้นได้)

ไม่ว่าในกรณีใด ลูกค้าจะต้องเตรียมใจไว้ว่าข้อมูลคำตอบอาจจะหายไป 

การจับคู่คำตอบกับผู้เข้าร่วม 

คำตอบมีเฉพาะลิงก์ไปยังผู้เข้าร่วมที่มีรายละเอียดอยู่ในเพย์โหลดการตอบสนองของจุดสิ้นสุดที่แยกจากกัน (ดูส่วน "แสดงรายชื่อผู้เข้าร่วมเกม") ลิงก์ดังกล่าวคือคุณสมบัติ participantId ที่มีอยู่ในเพย์โหลดทั้งสอง 

“คำตอบที่ถูกต้อง” หมายถึงอะไร 

ในกรณีของคำถามบางประเภท จะมีพื้นที่สีเทาอยู่ระหว่างสถานะคำตอบ "ไม่ถูกต้อง" และ "ถูกต้อง"

คำถามแบบเลือกตอบหลายข้อ 

ถูกต้อง - ผู้เข้าร่วมได้เลือกตัวเลือกที่ถูกต้องทั้งหมด และไม่มีตัวเลือกผิดเลย

PARTIALLY_CORRECT - ผู้เข้าร่วมได้เลือกอย่างน้อยหนึ่งในตัวเลือกที่ถูกต้องและไม่มีตัวเลือกผิดเลย ผิด - ผู้เข้าร่วมได้เลือกอย่างน้อยหนึ่งในตัวเลือกที่ผิด

คำถามเกี่ยวกับสไลเดอร์ 

ถูกต้อง - ผู้เข้าร่วมเลือกค่าที่ถูกต้องบนแถบเลื่อน

เกือบจะถูกต้อง - ผู้เข้าร่วมเลือกค่าที่ไม่แน่นอน แต่ยังคงอยู่ในค่าความคลาดเคลื่อนที่ผู้สร้าง kahoot ตั้งไว้ ผิด - ค่าที่เลือกอยู่นอกช่วงค่าความคลาดเคลื่อน

คำถามอื่นๆทั้งหมด 

สำหรับคำถามอื่น ๆ ทั้งหมดที่ สามารถ มีคำตอบที่ถูกหรือผิด มีเพียงสองตัวเลือกเท่านั้น: แก้ไข และ ผิด.

ความสัมพันธ์ระหว่างการหมดเวลาและคำตอบที่ถูกต้อง 

คำตอบของผู้เข้าร่วม วัตถุที่มีสถานะ เท่ากับ TIMEOUT จะไม่มีคุณสมบัติ คำตอบ ดังนั้นจึงไม่ใช่ "ถูกต้อง" หรือ "ผิด"  ขึ้นอยู่กับผู้ใช้ที่จะตัดสินใจว่าจะปฏิบัติอย่างไร พวกเขาจะได้รับคะแนนเป็นศูนย์เสมอในระหว่างเกม

นำเสนอข้อมูล API

มีหลายวิธีในการนำเสนอข้อมูล API ที่ถูกดึงออกมา นี่คือตัวอย่างของ Kahoot! ข้อมูลที่แสดงในรูปแบบภาพใน Power BI

💡พบว่าข้อมูลนี้มีประโยชน์หรือไม่? สมัครสมาชิกช่อง Youtube ของเราเพื่อรับเคล็ดลับเพิ่มเติมและ Kahoot! บทเรียน!