Kahoot 指南！ 報告 API

想知道如何使用 Kahoot！ 報告 API？ 以下是您開始之前需要了解的所有資訊。

快捷方式：

• 關於 Kahoot API
• 如何存取 API
• 使用 API 進行身份驗證
• 詞彙表
• 常見請求 - 操作指南

關於 Kahoot API 

Kahoot API 是遵循 OpenAPI 的 REST API。 您可以在 https://results.kahoot.com/swagger/查看我們所有的 API 文檔，包括資源和端點的詳細資訊。 

為了呼叫 Kahoot API，您的公司需要授權存取。 該 API 最適合擁有資料團隊或熟悉 API 的開發人員的客戶。 透過此 API，您的公司將能夠存取遊戲結束後過去 90 天內下面列出的所有資料。 我們對資料進行時間戳記，並支援客戶從我們的系統中提取資料的開始和結束日期。 

Kahoot API 報告有關遊戲、使用者、參與者、組織以及組織創建的 kahoot 的資訊。 有時候，我們在平台上的報道只能起到有限的作用。 對於頻繁使用產品或有大量參與者並希望追蹤其活動的客戶來說，API 是一種可擴展地實現這一目標的好方法。

如何存取 API

只有某些最高層級方案的客戶才可以獲得 API 授權。 如果您有興趣升級或啟動授權流程，請聯絡您的客戶成功經理。

使用 API 進行身份驗證

API 的身份驗證是透過使用 JWT 承載令牌來實現的，該令牌應在對 API 的每個請求的身份驗證標頭中提供。 令牌的有效期限為一小時，超過該時間則必須取得新的令牌。

要取得令牌，您首先需要一個客戶端 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 的請求中的承載令牌。 這表示所有請求的授權標頭都應具有「Bearer: <token>」形式的值。 如果您沒有正確地向 API 提供有效的令牌，則會傳回 401 回應。

詞彙表

常見請求 - 操作指南

• 如何列出遊戲參與者
• 誰是「參與者」？ 
• 查找遊戲
• 與 participantId 和 使用者 ID? 
• 如何取得參與者的電子郵件地址
• 如何列出答對至少 80% 問題的參與者
• 如果回傳 404 怎麼辦？ 
• 與參與者配對答案 
• 「正確答案」是什麼意思？
• 超時與正確答案的關係

如何列出遊戲參與者

誰是「參與者」？ 

以下步驟說明如何列出所有進入遊戲的玩家。 

請注意，「加入」與「積極參與」不同。 有可能由於連線問題或不注意而加入遊戲但無法回答任何問題。 此類參與者仍將被納入結果之中。 

查找遊戲 

請求 GET /v1/organisations/{organisationId}/games?limit={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,
}
],
cursor："abcxyz"
}

在結果中找到會話並記住它是 gameSessionId。 

列出遊戲參與者 

請求 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"

}

]

participantId 和 userId之間有什麼差別？ 

• participantId 是一個整數，無論遊戲選項如何，它始終存在。
• participantId 僅在本次遊戲會話中識別特定玩家。 在不同的遊戲會話中，相同的 participantId 可能並且通常指的是不同的人。 
• userId 僅包含在啟用了玩家識別碼選項的遊戲中。 那時，除了暱稱之外，還會要求玩家提供電子郵件等憑證。 或當他們透過電子郵件被邀請參加遊戲時。
• userId 使得在多個遊戲會話中追蹤同一個人成為可能。

如何取得參與者的電子郵件地址 

啟動 GET /v1/organisations/{organisationId}/users/{userId} 傳回的物件將包含 電子郵件 屬性。 

如何列出答對至少 80% 問題的參與者 

查找遊戲

請參閱查找遊戲的部分。 

尋找有關所播放的 kahoot 的資訊。 它分為兩部分： 

1. id - 引用已播放的 kahoot 的 UUID

2. 版本 - 遊戲結束後，kahoot 可能已被創作者編輯。 每次發生這種情況時，版本屬性都會增加。 這確保答案引用正確的數據。 

{

// other propperties

"kahootIdentifier"：{

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

"version"：5

},

}

取得參與者

請參閱列出參與者的部分。

獲取 kahoot 數據 

呼叫 GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} 取得 kahoot ，並根據 kahootIdentifier.id 和 kahootIdentifier.version 屬性取得查詢參數 。 

結果將包含 kahoot 包含的所有問題（區塊）以及可供參與者使用的答案選項（如果適用）。 問題和答案選項稍後將被答案文件引用。 

範例問題： 

{

"kahootIdentifier"：{

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

"version"：5

},

"title"："Kahoot title",

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

"questions"：[

{

"contentType"："CONTENT"

"blockIndex"：0

"title"：「這是公司簡報」

"description"："Some slide contents"

},

{

"contentType"："SINGLE_SELECT_QUIZ"

"blockIndex"：1

「問題」：「誰是我們最大的客戶？」 

 「選擇」：[

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

{"answerText"：「天網」, 「正確」: true}

]

},

]

}

獲得所有答案 

呼叫 GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers ，使用 搜尋遊戲時取得的 gameSessi onId (請參閱尋找遊戲章節) 和 blockIndex (即 kahoot 中問題的索引)。 需要對已播放的所有區塊（問題）進行迭代，排除那些根本不是問題的區塊（又稱內容）。 幻燈片）。 

以下範例顯示 kahoot 第二個區塊的答案，該區塊為單選測驗，參與者的身份為 parti cipantId=1234 (暱稱「Johnny」，如同 列出參與者的範例)，並選擇了第二個恰好正確的選項。 我們也可以看到暱稱「Robert」的參與者未能在規定時間內回答問題。

{

"blockIndexInKahoot"：1

「答案」：[

{

"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 屬性，存在於兩個有效載荷中。 

「正確答案」是什麼意思？ 

對於某些問題類型，答案狀態「不正確」和「正確」之間存在一些灰色區域。

多重測驗題 

正確 - 參與者選擇了所有正確的選項，沒有選擇任何錯誤的選項

部分正確 - 參與者至少選擇了一個正確的選項而沒有選擇錯誤的選項 錯誤 - 受試者至少選擇了一個錯誤的選項

滑桿問題 

正確 - 參與者在滑桿上選擇了正確的值

差不多正確 - 參賽者選擇的數值不準確，但在 kahoot 創建者設定的誤差範圍內 錯誤 - 選取的值超出公差範圍

所有其他問題 

對於所有其他問題 可以 只有兩個選項： 正確 和 錯誤.

超時與正確答案之間的關係 

狀態 等於 TIMEOUT 的 ParticipantAnswer 物件 不會有 答案 屬性，所以它們既不是「正確」也不是「錯誤」。  如何對待它們由使用者決定。 他們在遊戲中總是被分配零分。

呈現 API 資料。

有許多方式可以呈現擷取的 API 資料。 以下是 Kahoot 的範例！ 在 Power BI 中可視化的資料。

💡是否覺得有幫助？ 訂閱我們的 Youtube 頻道，以獲得更多提示和 Kahoot！ 教程！