카훗 가이드! 보고서 API
카훗 사용법이 궁금합니다! 보고서 API를 사용하시나요? 시작하기 위해 알아야 할 모든 것이 여기에 있습니다.
Kahoot API 정보
Kahoot API는 OpenAPI를 따르는 REST API입니다. 리소스 및 엔드포인트에 대한 세부 정보를 포함한 모든 API 설명서는 다음에서 확인할 수 있습니다. https://results.kahoot.com/swagger/.
Kahoot API를 호출하려면 귀사에서 인증된 액세스 권한이 필요합니다. 이 API는 데이터 팀이나 API에 익숙한 개발자가 있는 고객에게 가장 적합합니다. 이 API를 통해 귀사는 게임 종료 후 지난 90일 이내에 아래 나열된 모든 데이터에 액세스할 수 있습니다. 고객이 시스템에서 데이터를 가져오는 시점에 맞춰 데이터 타임스탬프와 지원 시작 및 종료 날짜를 지정합니다.
Kahoot API는 게임, 사용자, 참가자, 조직 및 해당 조직이 생성한 카후트에 관한 정보를 제공합니다. 때로는 플랫폼에서의 보고만으로는 한계가 있을 수 있습니다. 해당 제품을 자주 사용하거나 참가자 수가 많은 고객 중 활동 내역을 추적하고자 하는 분들에게, API는 이를 확장성 있게 구현할 수 있는 훌륭한 방법입니다.
API 액세스 방법
API 승인은 특정 최상위 요금제를 사용하는 고객만 사용할 수 있습니다. 인증 프로세스를 업그레이드하거나 시작하는 데 관심이 있는 경우 고객 성공 관리자에게 문의하세요.
API로 인증하기
API에 대한 인증은 JWT 베어러 토큰을 사용하여 이루어지며, 이 토큰은 API로 전송되는 각 요청의 ‘Authentication’ 헤더에 포함되어야 합니다. 토큰은 1시간 동안만 유효하며, 그 시간이 지나면 새로운 토큰을 받아야 합니다.
토큰을 발급받으려면 먼저 고객 성공 매니저로부터 제공받을 클라이언트 ID와 시크릿이 필요합니다. 이러한 인증 정보를 확보한 후에는 아래에 설명된 대로 당사의 인증 서버에 토큰을 요청해야 합니다.
| URL | https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token |
| Http 방법 | PUT |
| 권한 부여 헤더 | kahoot에서 제공한 자격 증명을 사용하여 기본 인증 제목을 제공해야 합니다. |
| 콘텐츠 유형 헤더 | application/x-www-form-urlencoded |
| 요청 본문 | 부여 유형=클라이언트 자격 증명 |
컬로 요청할 수 있는 예시는 아래와 같습니다:
curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Authorization: 기본 <다이제스트>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials요청에 대한 응답은 다음과 같은 구조를 갖습니다:
{
"access_token": "<API 요청에 사용할 토큰>",
"expires_in": 3600,
"refresh_expires_in": 0,
"토큰 유형": "무기명",
"not-before-policy": 0,
"scope": "이메일 프로필"
}API에 올바르게 인증하려면 API에 대한 요청에서 위 응답의 access_token 값을 베어러 토큰으로 사용해야 합니다. 즉, 모든 요청의 권한 부여 헤더에 "발신자: <토큰>" 형식의 값이 있어야 합니다. API에 유효한 토큰을 올바르게 제공하지 않은 경우 401 응답이 반환됩니다.
용어집
| 기간 | 설명 |
| 라이브 게임 | 카훗을 직접 플레이하는 경우. |
| 도전 과제 | 카훗이 비동기식으로 재생되는 경우. |
| 포인트 | 정수 값입니다. 플레이어가 이 질문에 대해 획득한 점수입니다. |
| 답변 | 질문에 대한 제출된 답변 집합입니다. |
| 수신, 시간 초과 | 질문에 대한 답변이 제공되었습니다. |
| 시간 초과 | 사용자가 질문에 대한 답변을 제공하지 않은 경우. |
| 블록 | 예를 들어 특정 유형의 문제를 항상 '블록'이라고 하는데, 참/거짓 문제 유형은 참/거짓블록, 브레인스토밍 문제 유형은 브레인스토밍블록이라고 합니다. |
| kahoot | 실제 카훗. 이는 게임이나 게임 세션(실제로 카훗을 플레이할 때 부르는 말)과는 다릅니다. |
| 게임 | 카훗이 재생되는 경우. |
| 게임 세션 | 고유한 게임 인스턴스입니다. |
| 호스트 | 게임을 실행한 사용자입니다. |
| 카훗 버전 | 카훗이 수정되면 해당 카훗의 다른 버전을 저장합니다. 다른 버전의 카훗이 재생될 수 있으며 따라서 다른 답이 저장될 수 있습니다. 0이 표시된 카훗의 버전은 버전이 지정되지 않은 것입니다. |
| 코스 | 일부 게임은 코스와 연결되어 있으며, 이 경우 코스 ID가 제공됩니다. |
| 블록 인덱스 - Kahoot | 게임이 원래 관련 카훗에 등장한 인덱스(0 기준)입니다. |
| 블록 색인 - 게임 |
게임 세션 중에 게임이 표시된 인덱스(0 기준)입니다. 질문 순서가 무작위로 사용된 경우 블록 인덱스인 카훗과 다를 수 있습니다. |
| 질문 | 카훗의 질문 목록입니다. |
| 브레인스토밍(질문 유형) | 참가자가 아이디어를 제출하고 투표하는 개방형 질문 유형입니다. |
| 드롭 핀(문제 유형) | 참가자가 이미지에 핀을 놓을 수 있는 포인트가 없는 문제입니다. |
| 설문 조사(질문 유형) | 플레이어가 문제에서 최대 6개의 옵션을 선택할 수 있는 무점수 문제입니다. |
| 다중 선택 퀴즈(문제 유형) | 플레이어에게 질문에서 선택할 수 있는 여러 가지 답변을 제공합니다. |
| 주관식(문제 유형) | 플레이어가 긴 형식의 텍스트 응답으로 답할 수 있는 질문입니다. |
| 퍼즐(문제 유형) | 플레이어가 올바른 순서로 답을 맞추는 문제입니다. |
| 슬라이더(문제 유형) | 참가자는 범위 내에서 정확한 숫자를 맞힙니다. |
| 참 거짓(문제 유형) | 참가자는 진술이 참인지 거짓인지 결정합니다. |
| 유형 답변(질문 유형) | 참가자는 짧은 형식의 텍스트로 답변합니다. |
| 워드 클라우드(질문 유형) | 짧은 자유 형식의 설문조사 질문을 수집하는 질문입니다. |
일반적인 요청 - 방법 안내
- 게임 참가자를 나열하는 방법
- "참여자"란 누구인가요?
- 게임 찾기
- 의 차이점은 무엇인가요? 참가자 ID 와 userId?
- 참가자의 이메일 주소를 얻는 방법
- 80% 이상 문제를 맞힌 참가자를 나열하는 방법
- 404가 반환되면 어떻게 하나요?
- 참가자와 답변 매칭하기
- "정답"이란 무엇을 의미하나요?
- 시간 초과와 정답의 관계
게임 참가자를 나열하는 방법
"참여자"란 누구인가요?
다음 단계에서는 게임에 참여한 모든 플레이어를 나열하는 방법을 설명합니다.
“가입”은 “적극적으로 플레이하는 것”과 다르다는 점에 유의해 주시기 바랍니다. 연결 문제나 주의를 기울이지 않아 게임에 참여하지 않고 질문에 답하지 못할 수도 있습니다. 이러한 참가자는 여전히 결과에 포함될 것입니다.
게임 찾기
GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} 을 호출하여 주어진 기간 동안 조직에서 플레이한 모든 게임을 나열합니다. 다른 결과 페이지를 사용할 수 있고 필요한 경우 커서 쿼리 매개변수를 추가합니다.
출력 예시에는 게임 세션 목록이 포함됩니다:
{
data: [
"게임세션아이디": "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358", "kahootIdentifier": {
"id": "3c28c370-0407-416f-a44f-087715b4ea89",
"version": 5
},
"startTime": 1667928438123,
}
],
커서: "abcxyz"
}결과에서 세션을 찾아 게임세션아이디 를 기억하세요 .
게임 참가자 목록
Invoke GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants 를 호출하여 게임에 참여한 모든 참가자를 나열합니다.
결과 예시:
[
{
"participantId": 1234,
"닉네임": "Johnny",
"userId": "f7e9a793-f223-4f2e-ad79-8bfa546a7180"
},
{
"participantId": 4321,
"닉네임": "Robert",
"userId": "a9555f0c-68b2-41b1-a540-49c34e15242e"
}
]참가자 아이디 와 사용자 아이디의 차이점은 무엇인가요?
- 참가자Id 는 정수이며 게임 옵션에 관계없이 항상 존재합니다.
- 참가자 아이디 는 이 게임 세션 내에서만 지정된 플레이어를 식별합니다. 다른 게임 세션에서 동일한 참가자 아이디 는 다른 사람을 지칭할 수 있으며, 일반적으로 다른 사람을 지칭합니다.
- userId 는 플레이어 식별자 옵션이 활성화된 게임에만 포함됩니다. 이때 플레이어는 닉네임 외에 이메일과 같은 자격 증명을 제공하라는 요청을 받게 됩니다. 또는 이메일을 사용하여 게임에 초대받은 경우.
- userId 를 사용하면 여러 게임 세션에서 동일한 사용자를 추적할 수 있습니다.
참가자의 이메일 주소를 얻는 방법
GET /v1/organisations/{organisationId}/users/{userId} 반환된 객체에는 이메일 속성이포함됩니다 .
80% 이상 문제를 맞힌 참가자를 나열하는 방법
게임 찾기
게임 찾기 섹션을 참조하세요.
재생된 카훗에 대한 정보를 찾습니다. 두 부분으로 구성되어 있습니다:
- id - 재생된 카훗을 참조하는 UUID입니다.
- 버전 - 카훗은 게임이 진행된 후 제작자가 편집했을 수 있습니다. 그럴 때마다 버전 속성이 증가합니다. 이렇게 하면 답변이 올바른 데이터를 참조할 수 있습니다.
{
// 다른 프로퍼티
"kahootIdentifier": {
"id": "3c28c370-0407-416f-a44f-087715b4ea89",
"version": 5
},
}참가자 확보
참가자 목록에 대한 섹션을 참조하세요.
카훗 데이터 가져오기
GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} 를 호출하여 kahootIdentifier.id 및 kahootIdentifier.version 속성을기반으로 쿼리 매개변수를 사용하여 kahoot를 가져옵니다 .
결과에는 카후트(Kahoot)에 포함된 모든 문제(블록)와, 해당되는 경우 참가자들이 선택할 수 있었던 답안 선택지가 모두 포함될 것입니다. 질문과 답변 선택지는 나중에 답안 문서에서 참조할 수 있습니다.
예시 문제:
{
"kahootIdentifier": {
"id": "3c28c370-0407-416f-a44f-087715b4ea89",
"version": 5
},
"title": "카훗 제목",
"설명": "이 카훗은 ... 에 관한 것입니다.",
"질문": [
{
"contentType": "CONTENT"
"blockIndex": 0
"title": "이것은 회사 프레젠테이션입니다"
"설명": "일부 슬라이드 내용"
},
{
"contentType": "SINGLE_SELECT_QUIZ"
"blockIndex": 1
"question": "우리의 최대 고객은 누구인가요?"
"선택": [
{"answerText": "미국의 아주 큰 회사", "correct": false},
{"answerText": "스카이넷", "정답": true}
]
},
]
}모든 답변 보기
게임을 검색할 때 얻은 게임세시 onId (게임 찾기 섹션 참조)와 카훗에서 질문의 인덱스인blockIndex 를사용하여 GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answer를 호출합니다 . 문제가 전혀 아닌 블록(일명 콘텐츠)을 제외하고 재생된 모든 블록(문제)을 반복해야 합니다. 슬라이드).
다음 예시는 카후트(Kahoot)의 두 번째 블록에 대한 정답을 보여줍니다. 이 블록은 단일 선택형 퀴즈였으며, participantId=1234인 참가자 ( 참가자 목록 예시 에 나와 있는 대로 닉네임은 “Johnny” )가 두 번째 선택지를 골랐고, 이 선택지가 정답이었습니다. 또한 "Robert"라는 닉네임을 가진 참가자가 제한 시간 내에 질문에 답하지 못했음을 알 수 있습니다.
{
"blockIndexInKahoot": 1
"answers": [
{
"participantId": 1234,
"answerStatus": "RECEIVED",
"answer": {
"type": "SINGLE_SELECT_QUIZ",
"choice": 1,
"correct": true,
"points": 900
}
},
{
"participantId": 4321,
"answerStatus": "timeout"
},
]
}선택 항목이 무엇인지, 참가자의 닉네임이 무엇인지 확인하려면 이전 섹션에서 언급한 관련 카훗 데이터와 참가자 데이터( )를 참조해야 합니다.
404가 반환되면 어떻게 하나요?
다음과 같은 경우 해당 블록의 답이 누락될 수 있습니다:
- 주어진 질문(블록)은 콘텐츠유형 입니다. '응답'은 잘 정의되어 있지 않습니다.
- 이 게임은 과제로 진행되었고 참가자들 중 3번 문제에 도달한 사람은 아무도 없었습니다.
- 게임 플레이 중 네트워크 문제가 발생하여 답변이 저장되지 않았습니다(드문 경우이지만 발생할 수 있음).
어떤 경우든 클라이언트는 답변 데이터가 누락될 수 있다는 점에 대비해야 합니다.
참가자와 답변 매칭하기
답변에는 별도의 엔드포인트의 응답 페이로드에 세부 정보가 포함된 참가자의 링크만 포함됩니다('게임 참가자 목록' 섹션 참조). 해당 링크는 참가자 아이디 두 페이로드에 모두 존재하는 속성입니다.
"정답"이란 무엇을 의미하나요?
일부 문제 유형의 경우 '오답'과 '정답' 상태 사이에 회색 영역이 존재합니다.
복수 선택형 퀴즈 문제
정답 - 참가자가 모든 정답을 선택하고 오답은 하나도 선택하지 않았습니다
부분적으로_정답 - 참가자가 정답 중 적어도 하나를 선택했고 오답은 하나도 선택하지 않았습니다 틀림 - 참가자가 오답 중 적어도 하나를 선택했습니다
슬라이더형 질문
정답 - 참가자가 슬라이더에서 올바른 값을 선택했습니다
거의_정답 - 참가자가 정확한 값은 아니지만, Kahoot 제작자가 설정한 허용 오차 범위 내에 있는 값을 선택했습니다 틀림 - 선택한 값이 허용 오차 범위를 벗어났습니다
그 외의 모든 질문
다음과 같은 기타 모든 문의 사항에 대해서는 정답이나 오답이 있을 수 있는 정답이나 오답이 있을 수 있는 모든 다른 질문의 경우, 선택지는 단 두 가지뿐입니다: 정답 와 틀림.
시간 초과와 정답의 관계
상태가 TIMEOUT인 참가자의 답변 객체는 속성을갖지 않으므로 "정답"도 "오답"도 아닙니다. 어떻게 처리할지는 사용자가 결정할 수 있습니다. 게임 중에는 항상 0점이 부여됩니다.
API 데이터 표시
추출된 API 데이터를 표시하는 방법에는 여러 가지가 있습니다. 다음은 카훗의 예입니다! Power BI에서 시각화된 데이터입니다.
💡 도움이 되셨나요? 더 많은 팁과 카훗을 보려면 유튜브 채널을 구독하세요! 튜토리얼!
댓글 0개
댓글을 남기려면 로그인하세요.