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.

Phím tắt:

• 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 lệnh gọi tới Kahoot API, công ty của bạn 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 báo cáo thông tin liên quan đến trò chơi, người dùng, người tham gia, tổ chức và 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 có nhiều người tham gia và muốn theo dõi hoạt động của họ, API là một cách tuyệt vời để thực hiện việc đó một cách có quy mô.

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

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

Để có được mã thông báo, trước tiên bạn sẽ cần ID khách hàng và bí mật do người quản lý thành công của khách hàng cung cấp. Sau khi có những thông tin xác thực 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 như mô tả bên dưới.

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 mô tả 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 giống 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ả mẫu sẽ bao gồm 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 lựa chọn câu trả lời có sẵn cho người tham gia 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â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 hiển thị câu trả lời cho khối thứ hai của kahoot, đó là một bài kiểm tra chọn lọc duy nhất, trong đó người tham gia được xác định bằng parti cipantId=1234 (biệt danh “Johnny” như trong ví dụ về danh sách người tham gia ) và chọn lựa chọn thứ hai tình cờ là đú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 lựa chọn đúng và không có lựa chọn sai nào

ĐÚNG_MỘT_PHẦN - người tham gia đã chọn ít nhất một trong những lựa chọn đúng và không có lựa chọn sai nào SAI - người tham gia đã chọn ít nhất một trong những lựa chọn sai

Câu hỏi về thanh trượt 

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

GẦN NHƯ ĐÚNG - người tham gia đã chọn một giá trị không chính xác nhưng nằm trong phạm vi dung sai do người tạo kahoot đặt ra SAI - giá trị đã 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 mà có có câu trả lời đúng hoặc sai, chỉ có hai lựa chọn: ĐÚNG và SA.

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!