카훗 가이드! 보고서 API

카훗 사용법이 궁금합니다! 보고서 API를 사용하시나요? 시작하기 위해 알아야 할 모든 것이 여기에 있습니다.

바로 가기:

Kahoot API 정보
API 액세스 방법
API로 인증하기
용어집
일반적인 요청 - 방법 안내

Kahoot API 정보

Kahoot API는 OpenAPI를 따르는 REST API입니다. 리소스 및 엔드포인트에 대한 세부 정보를 포함한 모든 API 설명서는 다음에서 확인할 수 있습니다. https://results.kahoot.com/swagger/.

회사에서 Kahoot API를 호출하려면 권한이 있는 액세스 권한이 필요합니다. 이 API는 데이터 팀이나 API에 익숙한 개발자가 있는 고객에게 가장 적합합니다. 이 API를 통해 귀사는 게임 종료 후 지난 90일 이내에 아래 나열된 모든 데이터에 액세스할 수 있습니다. 고객이 시스템에서 데이터를 가져오는 시점에 맞춰 데이터 타임스탬프와 지원 시작 및 종료 날짜를 지정합니다.

카훗 API는 게임, 사용자, 참가자, 조직, 조직에서 생성한 카훗과 관련된 정보를 보고합니다. 때로는 플랫폼에서의 보고만으로는 한계가 있을 수 있습니다. 제품을 자주 사용하거나 참여자 수가 많고 활동을 추적하고자 하는 고객에게는 API가 확장성 있게 이를 수행할 수 있는 좋은 방법입니다.

API 액세스 방법

API 승인은 특정 최상위 요금제를 사용하는 고객만 사용할 수 있습니다. 인증 프로세스를 업그레이드하거나 시작하는 데 관심이 있는 경우 고객 성공 관리자에게 문의하세요.

API로 인증하기

API에 대한 인증은 API에 대한 각 요청의 인증 헤더에 제공되어야 하는 JWT 베어러 토큰을 사용하여 이루어집니다. 토큰의 유효기간은 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개의 옵션을 선택할 수 있는 무점수 문제입니다.
다중 선택 퀴즈(문제 유형)	플레이어에게 질문에서 선택할 수 있는 여러 가지 답변을 제공합니다.
주관식(문제 유형)	플레이어가 긴 형식의 텍스트 응답으로 답할 수 있는 질문입니다.
퍼즐(문제 유형)	플레이어가 올바른 순서로 답을 맞추는 문제입니다.
슬라이더(문제 유형)	참가자는 범위 내에서 정확한 숫자를 맞힙니다.
참 거짓(문제 유형)	참가자는 진술이 참인지 거짓인지 결정합니다.
유형 답변(질문 유형)	참가자는 짧은 형식의 텍스트로 답변합니다.
워드 클라우드(질문 유형)	짧은 자유 형식의 설문조사 질문을 수집하는 질문입니다.

게임 참가자를 나열하는 방법

"참여자"란 누구인가요?

다음 단계에서는 게임에 참가한 모든 플레이어를 나열하는 방법을 설명합니다.

'가입'은 '활동 중'과는 다르다는 점에 유의하세요. 연결 문제나 주의를 기울이지 않아 게임에 참여하지 않고 질문에 답하지 못할 수도 있습니다. 이러한 참가자는 여전히 결과에 포함될 것입니다.

게임 찾기

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를 가져옵니다 .

결과에는 카훗에 포함된 모든 문제(블록)와 함께 참가자가 선택할 수 있는 답안(해당되는 경우)이 포함됩니다. 질문과 답변 선택지는 나중에 답안 문서에서 참조할 수 있습니다.

샘플 질문:

{

"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를 호출합니다 . 문제가 전혀 아닌 블록(일명 콘텐츠)을 제외하고 재생된 모든 블록(문제)을 반복해야 합니다. 슬라이드).

다음 예는 단일 선택 퀴즈인 카훗의 두 번째 블록에 대한 답으로, 참가자가 parti cipantId=1234 ( 참가자 목록 예시)로 식별하고 정답인 두 번째 선택지를 선택한 경우입니다. 또한 "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번 문제에 도달한 사람은 아무도 없었습니다.
게임 플레이 중 네트워크 문제가 발생하여 답변이 저장되지 않았습니다(드문 경우이지만 발생할 수 있음).

어떤 경우든 클라이언트는 답변 데이터가 누락될 수 있다는 점에 대비해야 합니다.

참가자와 답변 매칭하기

답변에는 별도의 엔드포인트의 응답 페이로드에 세부 정보가 포함된 참가자의 링크만 포함됩니다('게임 참가자 목록' 섹션 참조). 해당 링크는 참가자 아이디 두 페이로드에 모두 존재하는 속성입니다.

"정답"이란 무엇을 의미하나요?

일부 문제 유형의 경우 '오답'과 '정답' 상태 사이에 회색 영역이 존재합니다.

객관식 퀴즈 문제

정답 - 참가자가 정답을 모두 선택하고 오답을 하나도 선택하지 않음

partially_correct - 참가자가 정답 중 하나 이상을 선택했고 오답은 하나도 선택하지 않음 WRONG - 참가자가 잘못된 선택지 중 하나 이상을 선택했습니다.

슬라이더 질문

CORRECT - 참가자가 슬라이더에서 올바른 값을 선택했습니다.

ALMOST_CORRECT - 참가자가 정확하지는 않지만 카훗 작성자가 설정한 허용 오차 범위 내의 값을 선택했습니다. WRONG - 선택한 값이 허용 오차 범위를 벗어난 경우

기타 모든 질문

다른 모든 질문은 할 수 정답과 오답이 있는 다른 질문에는 두 가지 선택지만 있습니다: 정답 와 WRONG.

시간 초과와 정답의 관계

상태가 TIMEOUT인 참가자의 답변 객체는 속성을갖지 않으므로 "정답"도 "오답"도 아닙니다. 어떻게 처리할지는 사용자가 결정할 수 있습니다. 게임 중에는 항상 0점이 부여됩니다.

API 데이터 제시하기.

추출된 API 데이터를 표시하는 방법에는 여러 가지가 있습니다. 다음은 카훗의 예입니다! Power BI에서 시각화된 데이터입니다.

Power BI의 API 데이터 예제.png

💡 도움이 되셨나요? 더 많은 팁과 카훗을 보려면 유튜브 채널을 구독하세요! 튜토리얼!

댓글 0개

댓글을 남기려면 로그인하세요.

카훗 가이드! 보고서 API

관련 문서

Kahoot API 정보

API 액세스 방법

API로 인증하기

용어집

일반적인 요청 - 방법 안내

게임 참가자를 나열하는 방법

"참여자"란 누구인가요?

게임 찾기

게임 참가자 목록

참가자 아이디 와 사용자 아이디의 차이점은 무엇인가요?

참가자의 이메일 주소를 얻는 방법

80% 이상 문제를 맞힌 참가자를 나열하는 방법

게임 찾기

게임 찾기 섹션을 참조하세요.

참가자 확보

참가자 목록에 대한 섹션을 참조하세요.

카훗 데이터 가져오기

모든 답변 보기

404가 반환되면 어떻게 하나요?

참가자와 답변 매칭하기

"정답"이란 무엇을 의미하나요?

시간 초과와 정답의 관계

API 데이터 제시하기.