适用于 OneNote 课堂笔记本加载项集成的 LMS API 指南

项目
04/13/2017

适用于：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	字符串	可读学生名称
email	字符串	学生的官方电子邮件地址

检索课程的作业列表

生成 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 时使用
email	字符串	学生的官方电子邮件地址
已打分	布尔值	表明某一分数是否由教师打出
得分	整数	学生得分（例如 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 像素徽标。

通过