Проведи на Kahoot! звіти API

Не знаю, як використовувати Kahoot! звіти API? І ось все, що вам потрібно знати, щоб розпочати.

Комбінації:

• Про API Kahoot
• Як отримати доступ до API
• Автентифікація з API
• Glossary
• Загальні запити - Як керувати

Про API Kahoot 

API Kahoot є REST API, що слідує за OpenAPI. Ви можете переглянути всю нашу документацію по API, включаючи детальну інформацію про ресурси та кінцеві точки, за адресою https://results.kahoot.com/swagger/. 

Для того, щоб телефонувати в Kahoot API ваша компанія вимагатиме авторизованого доступу. API найкращий для клієнтів, які мають або команду з даними або розробників, які знайомі з API. За допомогою цього API ваша компанія зможе отримати доступ до всіх даних, перерахованих нижче за останні 90 днів після закінчення гри. Ми відзначаємо наші дані та дату початку та завершення підтримки, коли клієнт витягне дані з нашої системи. 

API Kahoot повідомляє про інформацію, яка стосується гри, користувачів, учасників, організацій та карахутрів, створених організацією. Іноді наші звітність на платформі можуть робити лише стільки. Для клієнтів, які використовують продукт часто або з великою кількістю учасників, і хочете відстежувати їх діяльність, API - це відмінний спосіб для масштабування.

Як отримати доступ до API

Авторизація API доступна лише для клієнтів на певних планах з найвищим рівнем доступу. Зверніться до свого менеджера успіху клієнта, якщо вас цікавить оновлення або ініціація процесу авторизації.

Автентифікація з API

Автентифікація для API досягається через використання JWT токена, який слід надати в заголовку аутентифікації кожного запиту в API. Токени час обмежений протягом години, після якої необхідно отримати новий токен.

Щоб отримати токен, вам спочатку знадобиться ідентифікатор клієнта та секрет, який буде надано вашим менеджером успіху клієнтів. Як тільки Ви маєте ці облікові дані, Ви повинні надіслати запит на маркер з нашого сервера аутентифікації, як описано нижче.

Приклад запиту, який може бути додано до кучеря, наведено нижче:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Авторизація: Basic <digest>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

Відповідь на запит буде мати наступну структуру:

{
"access_token": "<токен для використання в api запитах>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

Щоб автентифікувати API ви повинні використовувати значення access_token у вищевказаній відповіді в якості маркера вашого запиту на API. Це означає, що заголовок авторизації всіх запитів повинен мати значення у вигляді "Ведмеди: <token>”. Якщо ви неправильно ввели дійсний маркер для API, відповідь 401 буде повернута.

Glossary

Загальні запити - Як керувати

• Як перерахувати учасників гри
• Хто "учасник"? 
• Знайти гру
• Яка різниця між participantId та userId? 
• Як отримати адресу електронної пошти учасника
• Як перерахувати учасників, які отримали щонайменше 80% запитань
• А якщо повернути 404? 
• Відповідні відповіді з учасниками 
• Що означає "правильна відповідь"?
• Зв'язок між часом і правильною відповіддю

Як перерахувати учасників гри

Хто "учасник"? 

Наступні кроки описують, як скласти список всіх гравців, які увійшли до гри. 

Зверніть увагу, що "приєднання" не те саме, що "активне відтворення". Можна приєднатися до гри і не відповідати на будь-які питання через проблеми зв'язку чи не звертати увагу. Такі учасники все ще будуть враховані в результатах. 

Знайти гру 

Розібрати GET /v1/організації/{organisationId}/ігри? imit={limit}&startedSince={date} - щоб перелічити всі ігри в вашій організації заданий час. Додайтепараметр запитукурсору у випадку, якщо доступна інша сторінка результатів.

Приклад виводу буде містити список ігрових сесій:

{
data: [
"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/organizations/{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 в іншій ігровій сесії може відноситися і зазвичай відноситься до іншої людини. 
• userId включається лише в іграх з увімкненою опцією "Ідентифікатор гравця". Саме тоді, коли гравці просять ввести свої облікові дані, такі як email, додатково до псевдоніму. Або коли вони будуть запрошені до гри використовуючи свої електронні листи.
• userId дозволяє відстежувати одну й ту саму особу в кількох ігрових сесіях.

Як отримати адресу електронної пошти учасника 

Викличте GET /v1/organizations/{organisationId}/users/{userId} Повернутий об'єкт міститиме властивістьemail . 

Як перерахувати учасників, які отримали щонайменше 80% запитань 

Знайти гру

Дивіться секцію про пошук гри. 

Знайдіть інформацію про кахот, яка була відтворена. Він має дві частини: 

1. id - UUID, що посилається на кахот, який було відтворено

2. версія - кахут міг бути відредагований автором після того, як гра відбулася. Кожного разу, як воно стається, отримує підвищену версію властивостей. Це гарантує, що відповіді стосуються правильних даних. 

{

// інші властивості

"kahootIdentifier": {

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

"version": 5

},

}

Get participants

Дивіться розділ у списку учасників.

Отримати дані kahoot 

Invoke format@@2GET /v1/організацій/{organisationId}/kahoots/{kahootId}/versions/{version} щоб отримати kahoot з параметрами запиту на основі kahootIdentifier. d та kahootIdentifier.version властивостей. 

Результат повинен містити всі питання (блоки), що містяться поряд із вибором відповіді, який був доступний учасникам, якщо це застосовно. Питання та відповідь на вибір будуть згодом згадані документами відповіді. 

Приклади запитань: 

{

"kahootIdentifier": {

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

"version": 5

},

"title": "Назва кахуту",

"description": "Цей кахуд про ...",

"questions": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Це презентація компанії"

"description": "Деякий вміст слайдів"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"question": "Хто наш найбільший клієнт?" 

 "choices": [

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

{"answerText": "Скайнет", "correct": true}]

]

},

]

}

Отримати всі відповіді 

Викличте GET /v1/organizations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers , використовуючи gameSessi onId , отриманий під час пошуку гри (див. розділ "Знайти гру"), та blockIndex - індекс питання в кахоуті. Потрібно перебрати більше всіх блоків (запитань), що були у грі, без врахування запитань, що взагалі не були питаннями (вмісту aka. слайдів). 

У наступному прикладі показано відповідь на другий блок кахуту, який був вікториною з одним вибором, де учасник ідентифікувався як parti cipantId=1234 (нік "Johnny", як у прикладі зі списком учасників) і вибрав другий варіант відповіді, який виявився правильним. Ми також можемо бачити, що учасник з псевдонімом "Роберт" не встиг відповісти на питання в межах ліміту.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "ОТРИМАНО",

"answer": {

"type": "SINGLE_SELECT_QUIZ",

"choice": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Для того, щоб дізнатися, який був вибір і який нік учасника, потрібно звернутися до відповідних даних кахоуту та даних учасника , згаданих у попередніх розділах. 

А якщо повернути 404? 

Відповіді на заданий блок можуть бути відсутніми у наступних випадках: 

1. Дане питання (блок) має тип CONTENT. "Відповідь" їх не визначено. 
2. Гра була зіграна як призначення і жоден учасник не дійшов цього питання 3. 
3. Під час геймплею виникала проблема в мережі, і відповідь не була збережена (рідкісні випадки, але це можливо статися).

У будь-якому випадку, клієнтам необхідно бути готові, щоб дані про відповідь могли не знаходитись в цьому місці. 

Відповідні відповіді з учасниками 

Відповіді містять лише посилання на учасників, інформація про яких міститься в окремому корисному вантажі відповіді кінцевої точки (див. розділ "Список учасників гри"). Це посилання - participantId властивість, присутня в обох корисних навантаженнях. 

Що означає "правильна відповідь"? 

У разі деяких типів запитань існує деяка сіра область між "некорректною" та "правильним" статусом.

Тест на кілька запитань 

ПРАВИЛЬНО - учасник обрав усі правильні варіанти відповідей і жодного неправильного

ЧАСТКОВО_ПРАВИЛЬНО - учасник вибрав принаймні один з правильних варіантів відповіді і не вибрав жодного з неправильних НЕПРАВИЛЬНО - учасник вибрав принаймні одну з неправильних відповідей

Питання на слайдері 

ПРАВИЛЬНО - учасник вибрав правильне значення на повзунку

ALMOST_CORRECT - учасник вибрав значення, яке не є точним, але знаходиться в межах допуску, встановленого творцем кахоту WRONG - вибране значення вийшло за межі діапазону допуску

Усі інші питання 

З усіх інших питань, які можуть правильну або неправильну відповідь, є лише два варіанти: ПРАВИЛЬНА і НЕПРАВИЛЬНО.

Зв'язок між часовим видом та відповіддю 

Об'єкти ParticipantAnswer зі статусом , рівним TIMEOUT , не матимуть властивостівідповіді , тому вони не є ні "правильними", ні "неправильними".  Це залежить від користувача вирішити, як ставитися до них. Під час гри вони завжди отримують нуль балів.

Представлення даних API.

Існує багато способів представити витягнуті дані API. Ось приклад Kahoot! візуалізація даних у Power BI.

💡 Знайшли це корисним? Підписуйтесь на наш Youtube-канал, щоб отримати більше порад та Kahoot! уроки!