Hướng dẫn sử dụng Kahoot! báo cáo API

Bạn đang thắc mắc cách sử dụng Kahoot! báo cáo API? Sau đây là mọi thứ bạn cần biết để bắt đầu.

• Giới thiệu về Kahoot API
• Cách truy cập API
• Xác thực bằng API
• Thuật ngữ
• Yêu cầu chung - Hướng dẫn

Giới thiệu về Kahoot API 

Kahoot API là một REST API tuân theo OpenAPI. Bạn có thể xem lại toàn bộ tài liệu API của chúng tôi bao gồm thông tin chi tiết về tài nguyên và điểm cuối tại https://results.kahoot.com/swagger/. 

Để thực hiện các yêu cầu tới API Kahoot, công ty của quý vị sẽ cần có quyền truy cập được ủy quyền. API phù hợp nhất với những khách hàng có nhóm dữ liệu hoặc các nhà phát triển quen thuộc với API. Với API này, công ty của bạn sẽ có thể truy cập tất cả dữ liệu được liệt kê bên dưới trong vòng 90 ngày sau khi trò chơi kết thúc. Chúng tôi đóng dấu thời gian dữ liệu và hỗ trợ ngày bắt đầu và ngày kết thúc khi khách hàng lấy dữ liệu từ hệ thống của chúng tôi. 

API Kahoot cung cấp các báo cáo về thông tin liên quan đến trò chơi, người dùng, người tham gia, tổ chức và các trò chơi Kahoot do tổ chức đó tạo ra. Đôi khi, việc đưa tin của chúng tôi trên nền tảng này chỉ có thể làm được đến thế. Đối với những khách hàng sử dụng sản phẩm thường xuyên hoặc với số lượng người tham gia lớn, và muốn theo dõi hoạt động của họ, API là một giải pháp tuyệt vời để thực hiện điều đó một cách linh hoạt và có khả năng mở rộng.

Cách truy cập API

Quyền sử dụng API chỉ khả dụng đối với khách hàng đang sử dụng một số gói cao cấp nhất. Hãy liên hệ với người quản lý thành công của khách hàng nếu bạn quan tâm đến việc nâng cấp hoặc bắt đầu quy trình ủy quyền.

Xác thực bằng API

Việc xác thực cho API được thực hiện thông qua việc sử dụng mã thông báo JWT dạng bearer, mã thông báo này cần được cung cấp trong tiêu đề Authentication của mỗi yêu cầu gửi đến API. Thẻ có thời hạn sử dụng là một giờ; sau thời gian đó, người dùng phải lấy một thẻ mới.

Để nhận mã thông báo, trước tiên bạn cần có ID khách hàng và khóa bí mật, những thông tin này sẽ được người quản lý hỗ trợ khách hàng của bạn cung cấp. Sau khi có các thông tin đăng nhập này, bạn phải yêu cầu mã thông báo từ máy chủ xác thực của chúng tôi theo hướng dẫn dưới đây.

Một ví dụ về yêu cầu có thể thực hiện với curl được hiển thị bên dưới:

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

Phản hồi từ yêu cầu sẽ có cấu trúc như sau:

{
"access_token": "<token để sử dụng trong các yêu cầu API>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

Để xác thực đúng với API, bạn phải sử dụng giá trị của access_token trong phản hồi ở trên làm mã thông báo mang trong các yêu cầu của bạn tới API. Điều này có nghĩa là tiêu đề Authorization của tất cả các yêu cầu phải có giá trị ở dạng “Bearer: <token>”. Nếu bạn không cung cấp đúng mã thông báo hợp lệ cho API, phản hồi 401 sẽ được trả về.

Thuật ngữ

Yêu cầu chung - Hướng dẫn

• Cách liệt kê những người tham gia trò chơi
• “Người tham gia” là ai? 
• Tìm trò chơi
• Sự khác biệt giữa participantId và userId? 
• Làm thế nào để có được địa chỉ email của người tham gia
• Làm thế nào để liệt kê những người tham gia trả lời đúng ít nhất 80% câu hỏi
• Nếu trả về lỗi 404 thì sao? 
• Ghép câu trả lời với người tham gia 
• “Câu trả lời đúng” có nghĩa là gì?
• Mối quan hệ giữa thời gian hết hạn và câu trả lời đúng

Cách liệt kê những người tham gia trò chơi

“Người tham gia” là ai? 

Các bước sau đây hướng dẫn cách liệt kê tất cả người chơi đã tham gia trò chơi. 

Xin lưu ý rằng “tham gia” không đồng nghĩa với “chơi tích cực”. Bạn có thể tham gia trò chơi nhưng không trả lời bất kỳ câu hỏi nào do vấn đề kết nối hoặc không chú ý. Những người tham gia như vậy vẫn sẽ được tính vào kết quả. 

Tìm trò chơi 

Gọi GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} để liệt kê tất cả các trò chơi được chơi trong tổ chức của bạn trong một khung thời gian nhất định. Thêm tham số truy vấn con trỏ trong trường hợp có một trang kết quả khác khả dụng và cần thiết.

Kết quả đầu ra mẫu sẽ chứa một danh sách các phiên chơi game:

{
data: [
"gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89",  "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358",  "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version": 5 
},
"startTime": 1667928438123,
}
],
cursor: "abcxyz"
}

Tìm phiên trong kết quả và nhớ rằng đó là gameSessionId. 

Liệt kê những người tham gia trò chơi 

Gọi GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants để liệt kê tất cả những người tham gia trò chơi.

Kết quả mẫu: 

[

{

"participantId": 1234,

"nickname": "Johnny",

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

},

{

"participantId": 4321,

"nickname": "Robert",

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

}

]

Sự khác biệt giữa attendeeId và userIdlà gì? 

• attendeeId là một số nguyên và luôn có mặt bất kể tùy chọn trò chơi là gì.
• attendeeId chỉ xác định người chơi cụ thể trong phiên chơi này. Cùng một attendeeId trong một phiên trò chơi khác có thể và thường đề cập đến một người khác. 
• userId chỉ được bao gồm trong các trò chơi có tùy chọn Mã định danh người chơi được bật. Đó là lúc người chơi được yêu cầu cung cấp thông tin xác thực như email ngoài biệt danh. Hoặc khi họ được mời tham gia trò chơi bằng email của họ.
• userId cho phép theo dõi cùng một người trong nhiều phiên chơi trò chơi.

Làm thế nào để có được địa chỉ email của người tham gia 

Gọi GET /v1/organisations/{organisationId}/users/{userId} Đối tượng trả về sẽ chứa thuộc tính email . 

Làm thế nào để liệt kê những người tham gia trả lời đúng ít nhất 80% câu hỏi 

Tìm trò chơi

Xem phần tìm trò chơi. 

Tìm thông tin về kahoot đã được chơi. Nó có hai phần: 

1. id - UUID tham chiếu đến kahoot đã được chơi
2. phiên bản - kahoot có thể đã được người tạo chỉnh sửa sau khi trò chơi diễn ra. Mỗi lần điều đó xảy ra, thuộc tính phiên bản sẽ tăng lên. Điều này đảm bảo rằng các câu trả lời đề cập đến dữ liệu chính xác. 

{

// Các thuộc tính khác

"kahootIdentifier": {

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

"version": 5

},

}

Nhận người tham gia

Xem phần liệt kê những người tham gia.

Nhận dữ liệu kahoot 

Gọi GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} để lấy kahoot với các tham số truy vấn dựa trên kahootIdentifier.id và kahootIdentifier.version thuộc tính. 

Kết quả sẽ bao gồm tất cả các câu hỏi (khối) có trong Kahoot cùng với các phương án trả lời mà người tham gia có thể lựa chọn (nếu có). Các câu hỏi và lựa chọn trả lời sẽ được tham chiếu sau trong tài liệu trả lời. 

Các câu hỏi mẫu: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Kahoot title",

"description": "Kahoot này nói về ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Đây là bài thuyết trình của công ty"

"description": "Một số nội dung slide"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Khách hàng lớn nhất của chúng ta là ai?" 

 "choices": [

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

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

]

},

]

}

Nhận tất cả câu trả lời 

Gọi GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers bằng cách sử dụng gameSessi onId thu được khi tìm kiếm trò chơi (xem phần tìm trò chơi) và blockIndex là chỉ mục của câu hỏi trong kahoot. Người ta cần lặp lại tất cả các khối (câu hỏi) đã được chơi, loại trừ những khối không phải là câu hỏi (hay còn gọi là nội dung). slide). 

Ví dụ sau đây minh họa câu trả lời cho phần thứ hai của trò chơi Kahoot, vốn là một bài trắc nghiệm chọn một đáp án duy nhất, trong đó người tham gia có mã participantId=1234 (biệt danh “Johnny” như trong ví dụ danh sách người tham gia tại ) đã chọn đáp án thứ hai và đó chính là đáp án đúng. Chúng ta cũng có thể thấy rằng người tham gia có biệt danh “Robert” đã không trả lời được câu hỏi trong thời gian giới hạn.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "ĐÃ NHẬN",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Để biết lựa chọn nào là gì và biệt danh của người tham gia là gì, người ta cần tham khảo dữ liệu kahoot liên quan và dữ liệu của người tham gia đã đề cập ở các phần trước. 

Nếu trả về lỗi 404 thì sao? 

Câu trả lời cho một khối nhất định có thể bị thiếu trong các trường hợp sau: 

1. Câu hỏi (khối) đã cho có kiểu là NỘI DUNG. "Trả lời" những câu hỏi này vẫn chưa được định nghĩa rõ ràng. 
2. Trò chơi được chơi như một bài tập và không có người tham gia nào trả lời được câu hỏi đó 3. 
3. Đã xảy ra sự cố mạng trong quá trình chơi và câu trả lời không được lưu (trường hợp hiếm gặp nhưng vẫn có thể xảy ra).

Trong mọi trường hợp, khách hàng cần phải chuẩn bị tinh thần rằng dữ liệu trả lời có thể bị thiếu ở đó. 

Ghép câu trả lời với người tham gia 

Câu trả lời chỉ chứa các liên kết đến những người tham gia có thông tin chi tiết được chứa trong tải trọng phản hồi của điểm cuối riêng biệt (xem phần “Liệt kê những người tham gia trò chơi”). Liên kết đó là thuộc tính attendeeId có trong cả hai tải trọng. 

“Câu trả lời đúng” có nghĩa là gì? 

Trong trường hợp một số loại câu hỏi, có một khoảng mờ giữa trạng thái câu trả lời "sai" và "đúng".

Câu hỏi trắc nghiệm chọn nhiều đáp án 

ĐÚNG - người tham gia đã chọn tất cả các đáp án đúng và không chọn đáp án sai nào 

ĐÚNG MỘT PHẦN - Người tham gia đã chọn ít nhất một đáp án đúng và không chọn đáp án sai nào SAI - người tham gia đã chọn ít nhất một đáp án sai 

Câu hỏi dạng trượt 

ĐÚNG - người tham gia đã chọn giá trị chính xác trên thanh trượt 

GẦN ĐÚNG - Người tham gia đã chọn một giá trị không chính xác, nhưng vẫn nằm trong phạm vi dung sai do người tạo Kahoot đặt ra SAI - giá trị được chọn nằm ngoài phạm vi dung sai

Tất cả các câu hỏi khác 

Đối với tất cả các câu hỏi khác có thể có đáp án đúng hoặc sai, chỉ có hai lựa chọn: ĐÚNG và SAI.

Mối quan hệ giữa thời gian chờ và câu trả lời đúng 

Người tham giaTrả lời các đối tượng có trạng thái bằng với HẾT GIỜ sẽ không có thuộc tính câu trả lời , vì vậy chúng không "đúng" cũng không "sai".  Người dùng có quyền quyết định cách xử lý chúng. Họ luôn được cho điểm 0 trong suốt trò chơi.

Trình bày dữ liệu API

Có nhiều cách để trình bày dữ liệu API đã trích xuất. Dưới đây là một ví dụ về Kahoot! Dữ liệu được trực quan hóa trong Power BI.

💡 Bạn thấy điều này hữu ích? Đăng ký kênh YouTube của chúng tôi để nhận thêm mẹo và Kahoot! Hướng dẫn!