Kahoot 指南报告应用程序接口

想知道如何使用 Kahoot！报告 API？以下是您需要了解的入门知识。

• 关于 Kahoot API
• 如何访问应用程序接口
• 使用应用程序接口进行身份验证
• 术语表
• 常见要求 - 如何指南

关于 Kahoot API 

Kahoot API 是遵循 OpenAPI 的 REST API。您可以在以下网址查看我们所有的 API 文档，包括资源和端点的详细信息 https://results.kahoot.com/swagger/. 

若要调用 Kahoot API，贵公司需要获得授权访问权限。 API 最适合拥有数据团队或熟悉 API 的开发人员的客户。有了这个应用程序接口，贵公司就能在游戏结束后的 90 天内访问以下列出的所有数据。我们会给数据加上时间戳，并支持客户从我们的系统中提取数据的开始和结束日期。 

Kahoot API 提供有关游戏、用户、参与者、组织以及该组织创建的 Kahoot 的信息。有时，我们在平台上的报道只能做到这一点。对于频繁使用该产品或参与人数较多的客户，如果希望跟踪其活动情况，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，您必须在向 API 提出的请求中使用上述响应中的 access_token 值作为承载令牌。这意味着所有请求的授权标头的值都应为 "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,

"nickname"："Johnny",

"userId"："f7e9a793-f223-4f2e-ad79-8bfa546a7180"

},

{

"participantId"：4321,

"nickname"："Robert",

"userId"："a9555f0c-68b2-41b1-a540-49c34e15242e"

}

]

participantId和userId 有什么区别？ 

• participantId 是一个整数，无论游戏选项如何，它始终存在。
• participantId 仅用于识别本游戏会话中的指定玩家。同一participantId 在不同的游戏环节中可能指不同的人，通常也确实如此。 
• userId 只包含在启用了玩家标识符选项的游戏中。这时，除了昵称外，还要求球员提供电子邮件等证书。或者用他们的电子邮件邀请他们参加比赛。
• 用户 ID 可以在多个游戏会话中跟踪同一个人。

如何获取与会者的电子邮件地址 

调用 GET /v1/orisations/{organisationId}/users/{userId} 返回的对象将包含 电子邮件 属性。 

如何列出至少答对 80% 问题的参与者名单 

查找游戏

请参阅 "查找游戏"部分。 

查找所玩游戏的相关信息。它包括两个部分： 

1. id - UUID 指的是播放过的 kahoot
2. 版本 - Kahoot 可能在游戏结束后被创作者编辑过。每次发生这种情况时，版本属性都会递增。这样可以确保答案参考的是正确的数据。 

{

// other propperties

"kahootIdentifier"：{

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

"version"：5

},

}

获取参与者

请参阅 "与会者名单 "部分.

获取 kahoot 数据 

根据 kahootIdentifier.id 和 kahootIdentifier.version 属性，调用 GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} 获取带有查询参数的 kahoot 。 

结果将包含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"："一些幻灯片内容"

},

{

"contentType"："SINGLE_SELECT_QUIZ"

"blockIndex"：1

"问题"："谁是我们最大的客户？ 

 "选择"：[

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

{"answerText"："天网"，"正确"： true}

]

},

]

}

获取所有答案 

调用 GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers ，使用 查找游戏时获得的 gameSessi onId （请参阅查找游戏部分）和 blockIndex （即 kahoot 中问题的索引） 。我们需要遍历所有播放过的区块（问题），排除那些根本不是问题的区块（内容）。幻灯片）。 

以下示例展示了Kahoot第二题块的答案，该题块为单选题，其中参与者ID为 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！教程！