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 的每則請求的「Authentication」標頭中。代幣的有效時間為一小時，過後必須取得新的代幣。

要取得存取憑證，您首先需要一個客戶 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 第二題區的答案，該題為單一選項測驗，其中參與者 （ 其 participantId=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！教程！