Kahoot!ガイド レポートAPI

Kahoot！の使い方を知りたい reports API? ここでは、始めるために必要な情報をご紹介します。

ショートカット

• Kahoot APIについて
• APIへのアクセス方法
• APIによる認証
• 用語集
• よくあるリクエスト - How To Guide

Kahoot APIについて 

Kahoot APIは、OpenAPIに準拠したREST APIです。 リソースやエンドポイントの詳細を含む、私たちのすべてのAPIドキュメントは、 https://results.kahoot.com/swagger/で確認することができます。 

Kahoot APIを呼び出すには、お客様の会社で認可されたアクセス権が必要です。 APIは、データチームやAPIに精通した開発者をお持ちのお客様に最適です。 本APIを利用することで、貴社はゲーム終了後、過去90日以内に以下の全てのデータにアクセスすることができます。 私たちはデータにタイムスタンプを打ち、お客様が私たちのシステムからデータを引き出す際の開始日と終了日をサポートします。 

Kahoot APIは、ゲーム、ユーザー、参加者、組織、組織が作成したkahootsに関連する情報を報告します。 私たちがプラットフォーム上で行う報道は、時に限られたものでしかありません。 製品の利用頻度が高い、あるいは参加人数が多く、その行動を追跡したいお客様にとって、APIはスケーラブルにそれを実現する素晴らしい手段です。

APIへのアクセス方法

API の認可は、特定の最上位プランのお客様のみご利用いただけます。 アップグレードまたは認証プロセスの開始にご興味のある方は、カスタマーサクセスマネージャーにお問い合わせください。

APIによる認証

API の認証は、JWT ベアラートークンの使用により実現されます。このトークンは、API への各リクエストの Authentication ヘッダーで提供される必要があります。 トークンには1時間という時間制限があり、それを過ぎると新しいトークンを取得しなければなりません。

トークンを取得するためには、まず、カスタマーサクセスマネージャーから提供されるクライアントIDとシークレットが必要です。 これらの認証情報を入手したら、以下に示すように、当社の認証サーバーにトークンを要求する必要があります。

curlを使ったリクエストの例を以下に示す。

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

リクエストからの応答は以下のような構造になっています。

{
"access_token"："<apiリクエストで使用するトークン>",
"expires_in"：3600,
"refresh_expires_in"：0,
"token_type"："Bearer",
"not-before-policy"：0,
"scope"："email profile"
}.

API に対して適切に認証を行うには、上記のレスポンスに含まれる access_token の値を、API へのリクエストの際にベアラートークンとして使用する必要があります。 これは、すべてのリクエストのAuthorizationヘッダーの値が、"Bearer: <token>". APIに有効なトークンが正しく入力されていない場合、401応答が返されます。

用語集

よくあるリクエスト - How To Guide

• ゲーム参加者のリストアップ方法
• 参加者」とは誰のことですか？ 
• ゲームを探す
• の違いは何ですか？ 参加者ID と ユーザーID? 
• 参加者のメールアドレスの取得方法
• 8割以上正解した参加者をリストアップする方法
• 404が返ってきた場合は？ 
• 参加者と答え合わせをする 
• 正解」とはどういう意味ですか？
• タイムアウトと正解の関係

ゲーム参加者のリストアップ方法

参加者」とは誰のことですか？ 

以下の手順で、ゲームに参加したすべてのプレイヤーをリストアップする方法を説明します。 

なお、「参加すること」と「積極的にプレイすること」は同じではありません。 ゲームに参加しても、回線の問題や注意力不足で何も答えられないこともあり得ます。 そのような参加者も、やはり結果に含まれることになります。 

ゲームを探す 

GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} を実行すると、指定した期間に組織で行われたすべてのゲームが一覧表示されます。 結果の別のページが利用可能で必要な場合に備えて、 カーソル クエリパラメータを追加しました。

サンプル出力には、ゲームセッションのリストが含まれます：

{
データ：[
"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/organisations/{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 このゲームセッション内でのみ、指定されたプレーヤーを識別します。 別のゲームセッションで同じ participantId が別人を指す場合もあり、通常はそうなります。 
• userId は、Player Identifier オプションが有効になっているゲームにのみ含まれます。 その際、ニックネームだけでなく、Eメールなどの認証情報を提供してもらうのです。 あるいは、電子メールを使ってゲームに招待されたとき。
• userId 、複数のゲームセッションで同一人物を追跡することが可能になります。

参加者のメールアドレスの取得方法 

Invoke GET /v1/organisations/{organisationId}/users/{userId} 返されるオブジェクトには email プロパティが含まれます。 

8割以上正解した参加者をリストアップする方法 

ゲームを探す

ゲームの検索についてのセクションを参照してください. 

再生されたカフートに関する情報を探す。 2部構成になっています。 

1. id - 再生されたカフートを参照するUUID

2. version - カフートは、ゲームが行われた後に作成者によって編集された可能性があります。 その都度、versionプロパティがインクリメントされる。 これにより、回答が正しいデータを参照していることが確認できます。 

{

// その他のプロパティー

"kahootIdentifier"：{

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

"version"：5

},

}.

参加者募集

参加者のリストアップの項を参照.

カフートデータを取得する 

GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} を呼び出し、 kahootIdentifier.id と kahootIdentifier.version のプロパティに基づいてクエリーパラメータでカフートを取得することが可能です。 

結果には、カフートで出題されたすべての問題（ブロック）と、参加者が選択可能な回答（該当する場合）が含まれます。 問題や解答の選択肢は、後で解答資料で参照することになる。 

サンプル問題です。 

{

"kahootIdentifier"：{

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

"version"：5

},

"title"："Kahoot title",

"description"："This kahoot is about ...",

"questions"：[

{

"contentType"："CONTENT"

"blockIndex"：0

"title"："This is the company presentation"

"description"："Some slide contents"

},

{

"contentType"："SINGLE_SELECT_QUIZ"

"blockIndex"：1

"question"：「最大の顧客は誰ですか？ 

 "選択肢"：[

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

{"answerText"："スカイネット", "correct": true}.

]

},

].

}

すべての回答を取得する 

GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers gameSessi onId ゲームを探したときに得られたもの（ゲームの検索セクション参照）と blockIndex kahoot の質問のインデックスを使って呼び出す。 質問でないもの（コンテンツ）を除いて、再生されたすべてのブロック（質問）を反復する必要があります。 のスライド）。 

次の例は、単一選択クイズであるkahootの2番目のブロックに対する回答です。参加者は parti cipantId=1234 ( リスト参加者の例のようにニックネーム「Johnny」) と識別し、たまたま正解だった2番目の選択肢を選択しました。 また、「ロバート」というニックネームの参加者は、制限時間内に質問に答えることができなかったことがわかります。

{

"blockIndexInKahoot"：1

"answers"：[

{

"participantId"：1234,

"answerStatus"："RECEIVED",

"answer"：{

"type"："SINGLE_SELECT_QUIZ",

"choice"：1,

"correct": true,

"points"：900

}.

},

{

"participantId"：4321,

"answerStatus"："timeout"

},

].

}

参加者のニックネームを知るためには、前節で紹介した関連する kahoot データ と 参加者のデータ を参照する必要があります。 

404が返ってきた場合は？ 

あるブロックの回答が欠落するのは、次のような場合です。 

1. 与えられた質問（ブロック）のタイプは CONTENTです。 "答える "ということが、うまく定義されていない。 
2. ゲームは課題として行われ、その設問3に到達した参加者はいなかった。 
3. ゲームプレイ中にネットワークの問題が発生し、回答が保存されなかった（まれなケースだが、起こりうることである）。

いずれにせよ、お客様はそこで回答データが欠落する可能性があることを覚悟しておく必要がある。 

参加者と答え合わせをする 

回答には、別のエンドポイントの応答ペイロードに詳細が含まれている参加者へのリンクのみが含まれます (「ゲームの参加者のリスト」セクションを参照)。 そのリンクは、 participantId 両方のペイロードに存在するプロパティである。 

正解」とはどういう意味ですか？ 

問題の種類によっては、「不正解」と「正解」の間にグレーゾーンが存在するものもあります。

複数選択可能なクイズ問題 

CORRECT - 参加者は正しい選択肢をすべて選択し、間違った選択肢は一つも選択しなかった

PARTIALLY_CORRECT - 参加者は正しい選択肢を少なくとも1つ選択し、間違った選択肢は1つも選択しなかった WRONG - 参加者は間違った選択肢のうち少なくとも1つを選択した

スライダーに関する質問 

CORRECT - 参加者は、スライダーで正しい値を選択した

ALMOST_CORRECT - 参加者は、正確ではないが、kahootクリエイターが設定した許容範囲内の値を選択した WRONG - 選択した値が許容範囲外であった

その他の質問 

その他の質問については については 選択肢は2つだけです： 正解 と 不正解.

タイムアウトと正解の関係 

ParticipantAnswer オブジェクトで ステータス が TIMEOUT と等しいものは、 答え プロパティを持つことにならないので、「正しい」でも「間違っている」でもないのである。  どのように扱うかは、ユーザーの自由です。 ゲーム中は常に0点が割り当てられている。

APIデータの提示

抽出されたAPIデータを表示する方法はたくさんある。 Kahootの例です！ Power BIで可視化されたデータ。

お役に立ちましたか？ Youtubeチャンネルに登録して、より多くのヒントやKahootをお楽しみください！ チュートリアル