适用于 OneNote 课堂笔记本加载项集成的 LMS API 指南
适用于：Office 365 上的企业笔记本
本文档提供了 OneNote 在任何 LMS 中列举课程和作业、布置作业、下载成绩和更新成绩时所需调用的 API。
所有请求均应接受认证。 所有请求均应通过 HTTPS 发送。
备注
我们建议各 LMS 均应在执行 oauth2 时采用授权代码授予流程。 这样可为用户免去每次在访问令牌过期时不得不输入凭据的麻烦。
检索课程的列表
生成 GET 请求并发送至 <Specify URL for retrieving list of classes>。
LMS 应返回当前认证用户的课程 JSON 数组。
各课程应具备如下属性：
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 课程标识符，仅在安装 LMS 时使用 |
| name | 字符串 | 可读课程名称 |
检索课程中的学生列表
生成 GET 请求并发送至 <Specify URL for retrieving list of students in a class>。
LMS 应返回课程中的学生 JSON 数组。
各学生均应具备如下属性：
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 学生标识符，仅在安装 LMS 时使用 |
| name | 字符串 | 可读学生名称 |
| 字符串 | 学生的官方电子邮件地址 |
检索课程的作业列表
生成 GET 请求并发送至 <Specify URL for retrieving list of assignments for a class>。
LMS 应返回课程的作业 JSON 数组。
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 作业标识符，仅在安装 LMS 时使用 |
| title | 字符串 | 作业标题 |
| description | 字符串 | 作业描述 |
| gradetypeid | 字符串 | 成绩类型标识符，仅在安装 LMS 时使用 |
| dueDate | 字符串格式日期（格式：2016-12-25 时间 00：00：00） | 作业截止日期。 LMS 不会存储或使用时间信息。 |
| url | 字符串 | 作业 URL。 仅可在受其支持的 LMS 版本中使用。 |
| 可选属性名称 | 类型 | 说明 |
|---|---|---|
| gradetypeid | 字符串 | 成绩类型标识符，仅在安装 LMS 时使用 |
| min | 整数 | 可向学生分配的最低分数 |
| max | 整数 | 可向学生分配的最高分数 |
| validgradevalues | 列表 | 此次作业适用的有效成绩分值 |
为课程布置作业
生成 POST 请求并发送至 <Specify URL for setting an assignment to a class>。
需使用以下窗体 POST 变量：
| 属性名 | 类型 | 说明 |
|---|---|---|
| title | 字符串（最大长度：280） | 作业标题 |
| dueDate | 字符串格式日期（格式：2016-12-25 时间 00：00：00） | 作业截止日期 |
| description | 字符串 | 作业描述 |
| 可选属性名称 | 类型 | 说明 |
|---|---|---|
| gradetypeid | 字符串 | 成绩类型标识符，仅在安装 LMS 时使用 |
| min | 整数 | 可向学生分配的最低分数 |
| max | 整数 | 可向学生分配的最高分数 |
| validgradevalues | 列表 | 此次作业适用的有效成绩分值 |
LMS 将返回具备单一 id 属性的 JSON 对象。 此属性值将作为新布置作业的标识符。
检索作业成绩列表
生成 GET 请求并发送至 <Specify URL for retrieving grades for a given assignment>。
LMS 应返回收到作业的学生及其成绩/分数的 JSON 数组。
各学生的 JSON 字段均应具备如下属性：
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 学生标识符，仅在安装 LMS 时使用 |
| 字符串 | 学生的官方电子邮件地址 | |
| 已打分 | 布尔值 | 表明某一分数是否由教师打出 |
| 得分 | 整数 | 学生得分（例如 85） |
| 最高分 | 整数 | 最高可得分（例如 100） |
| feedback | 字符串 | 可向学生提供的反馈（例如，" 完成得很出色"） |
| grade | 字符串 | 可为学生打出的成绩（例如， "A " ） |
请注意，LMS 可能支持以除 100 外的其他数字进行打分。 在上述情况下（最高分不等于 100 ），如果分数未能在 OneNote UI 中显示，则 OneNote 可能需对所获分数进行转换。
为学生打分
生成 POST 请求并发送至 <Specify URL for setting grade for a given student>。
可包含以下窗体 POST 变量：
| 属性名 | 类型 | 说明 |
|---|---|---|
| ** id** | 字符串 | 学生标识符是一款全球唯一标识符 |
| source | 字符串 | 始终将值设置为 " onenote" |
| obtainedMark | 整数 | 学生得分 |
| 最高分 | 整数 | 最高可得分 |
| 得分 | 字符串 | 学生得分或当前水平（例如： "A"） |
| comments | 字符串 | 学生的自由文本反馈 |
获得成绩类型
生成 GET 请求并发送至 <Specify URL for getting grade types>。
LMS 应返回成绩类型 JSON 数组。 各成绩类型均应具备以下属性：
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 成绩类型标识符，仅在安装 LMS 时使用 |
| 成绩类型分类 | 成绩类型分类 | 成绩类型标识符，仅在安装 LMS 时使用 |
| max | 整数 | 可能的最大分数 |
| description | 字符串 | 显示成绩类型字符串 |
获得具体成绩类型
生成 GET 请求并发送至 <Specify URL for getting grade type by id>。
LMS 应返回单一成绩类型 JSON，且需具备如下属性：
| 属性名 | 类型 | 说明 |
|---|---|---|
| id | 字符串 | 成绩类型标识符，仅在安装 LMS 时使用 |
| 成绩类型分类 | 成绩类型分类 | 成绩类型标识符，仅在安装 LMS 时使用 |
| max | 整数 | 可能的最大分数 |
| description | 字符串 | 显示成绩类型字符串 |
创建/删除课程及删除作业
它们供选用，但如需进行集成测试，则我们强烈建议采用。 Microsoft 课堂笔记本团队将使用这些端点进行清理。
enum GradeTypeCategory
{
/// <summary>
/// no grade type category.
/// </summary>
None,
/// <summary>
/// Numeric grade type category.
/// </summary>
Numeric,
/// <summary>
/// Percent grade type category.
/// </summary>
Percentage,
/// <summary>
/// Letter grade type category.
/// </summary>
Letters,
}
测试环境的先决条件
测试环境由两个系统组成：
Office 365 测试租户
可为您有权访问的任一 Office 365 租户，需具备有效 Office 授权且其中应含数个教师帐号及学生帐号。
合作伙伴可使用演示 Office 365 租户。 设置此演示租户时，您可选择自定义 K–12 EDU 实例，该实例内含有预设的教师、学生以及教育 SKU。
LMS 测试环境和帐号
您需向课堂笔记本团队提供以下信息 -
- 用于托管 API 端点的 LMS/SIS 的基本 Url。
- 应用程序 ID（如果不支持 oauth2）：分配给课堂笔记本加载项的唯一应用程序 ID，允许您检测并确认为有效的应用程序。
- 应用程序密钥 （如果不支持 oauth2）：给定应用程序 ID 的应用程序机密。
市场营销信息必备组件
徽标图像。 该图像不一定具备超高分辨率。 我们当前徽标实际上是不超过 100 K 大小，最高为 300 x 300 最大。
描述 。 请尽量就您的产品及服务进行简短说明，长度约为 75 字 （50 字左右更佳）。
链接至您的网站。 用于进一步了解您的产品及服务信息。
按钮徽标。 应为 64 x 64 像素徽标。