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。 如果您对升级或启动授权流程感兴趣，请联系您的客户成功经理。

使用应用程序接口进行身份验证

应用程序接口的身份验证是通过使用 JWT 承载令牌实现的，每次向应用程序接口发出请求时，都应在 "身份验证 "标头中提供该承载令牌。 令牌有一小时的时限，一小时后必须获取新令牌。

要获取令牌，您首先需要一个客户 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 第二部分的答案，这是一个单选测验，参与者的身份是 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！ 教程！