使用异步课堂笔记本
适用于：Office 365 上的企业笔记本
世界各地的中小学校、学院和大学都在使用课堂笔记本，帮助促进生产力、参与和协作。 您可以为每个课堂、项目、学期和作业使用课堂笔记本。
ClassNotebooks 端点用于执行课堂笔记本的常见任务，如创建异步调用的课堂笔记本，以及添加或移除学生。
备注
OneNote API 提供 classNotebooks 端点，用于课堂笔记本特定的操作。
异步 API
若要对 classNotebooks 端点进行异步调用，发送带标头 Prefer: respond-async 的请求。
响应
| 响应数据 | 说明 |
|---|---|
| 成功代码 | 202 状态 HTTP 状态码。 |
| 位置标头 | 用于轮询操作状态的 URL。 轮询操作端点将返回一个包含操作状态和其他信息的 OperationModel 对象。 |
| X-CorrelationId 标头 | 唯一标识该请求的 GUID。 在与 Microsoft 支持部门协作来解决问题时，可以使用此值和日期标头值。 |
操作模式
| 操作模式 | 说明 |
|---|---|
| Id | 操作的 ID。 |
| 状态 | 状态可以是以下：已完成，正在运行，未启动或失败。 - 如果是已完成，则 resourceLocation 属性将包含新 classNotebook 的资源端点。 - 如果是正在运行，createdDateTime 和 lastActionDateTime 会显示创建请求的时间和上次运行的时间。 - 如果是失败，error 和 @ api.diagnostics 属性将提供错误信息。 |
| createdDateTime | 显示创建请求的时间。 |
| lastActionDateTime | 显示创建请求的时间和上次运行的时间。 |
| resourceLocation | 资源的端点。 |
| resourceId | 资源的 ID。 |
构建请求 URI
要构建请求 URI，请参阅主题使用课堂笔记本 中的构建请求 URI。
创建课堂笔记本
若要创建异步调用的课堂笔记本，向 classNotebooks 端点发送带标头 Prefer: respond-async 的 POST 请求。
POST ../classNotebooks
对于邮件正文和带课堂笔记本创建参数的 JSON 对象，请参阅创建课堂笔记本。
示例
以下请求将创建一个名为 Math 101 的课堂笔记本。
请求
POST https://www.onenote.com/v1.0/me/notes/classNotebooks?sendemail=true
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"name": "Math 101",
"studentSections": [
"Handouts",
"Class Notes",
"Homework",
"Quizzes"
],
"teachers": [
{
"id": "teacher1@contoso.com",
"principalType": "Person"
}
],
"students": [
{
"id": "student1@contoso.com",
"principalType": "Person"
},
{
"id": "student2@contoso.com",
"principalType": "Person"
},
{
"id": "student3@contoso.com",
"principalType": "Person"
},
{
"id": "student4@contoso.com",
"principalType": "Person"
}
],
"hasTeacherOnlySectionGroup": true
}
响应
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
轮询操作 Location 端点，以获取创建课堂操作的状态。
请求
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebook-ee91aafb-5685-4357-9465-77d611ef064c
响应
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebook-ee91aafb-5685-4357-9465-77d611ef064c",
"status":"completed",
"createdDateTime":"2018-06-01T23:44:29.349Z",
"lastActionDateTime":"2018-06-01T23:44:29.349Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e",
"resourceId":"1-cb6e0bf6-1185-4daa-80a1-ded42ca1708e"
}
添加学生和教师
添加学生和教师使其能访问课堂笔记本。 添加学生还将创建学生模块组。 此模块组仅可由学生和教师访问，且包含为笔记本定义的学生模块。
若要在异步调用中添加学生或教师到课堂笔记本，向适当端点发送带标头 Prefer: respond-async 的POST 请求。
添加学生
POST ../classNotebooks/{notebook-id}/students
添加教师
POST ../classNotebooks/{notebook-id}/teachers
对于邮件正文和带课堂笔记本创建参数的 JSON 对象，请参阅添加学生或教师。
示例
以下请求添加教师到指定的课堂笔记本。
请求
POST https://www.onenote/api/v1.0/me/notes/classNotebooks/ 1-b68a21fd-cdb3-41f1-a566-0772872a8a0c//teachers
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"id": "teacher2@contoso.com",
"principalType": "Person"
}
响应
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
轮询操作 Location 端点以获取添加教师操作的状态。
请求
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9
响应
{
"@odata.context":"https://www.onenote/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-28d4f01e-32f1-4e82-866e-025b1f2ca2b9",
"status":"completed",
"createdDateTime":"2018-06-12T22:23:47.548Z",
"lastActionDateTime":"2018-06-12T22:23:47.548Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
移除学生和教师
从课堂笔记本移除学生和教师，将撤消他们对笔记本的访问权限，但不会删除任何内容。 若要删除异步调用的课堂笔记本中的学生或教师，向适当端点发送带标头 Prefer: respond-async 的 DELETE 请求。
删除学生
DELETE ../classNotebooks/{notebook-id}/students/{student-id}
移除教师
DELETE ../classNotebooks/{notebook-id}/teachers/{teacher-id}
可以根据要求移除学生或教师。
示例
以下请求将从指定的课堂笔记本移除指定的教师。
请求
DELETE https://www.onenote.com/api/v1.0/me /notes/classNotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net
Authorization: Bearer {token}
Accept: application/json
Prefer: respond-async
响应
HTTP/1.1 202 Accepted
Location: https://www.onenotecom/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
轮询操作 Location 端点以获取删除教师操作的状态。
请求
GET https://www.onenote.com/api/v1.0/me/notes/operations/classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a
响应
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"classnotebookmember-e364e1fe-11a1-4551-8dcc-a143a8c0d78a",
"status":"completed",
"createdDateTime":"2018-06-12T22:40:06.708Z",
"lastActionDateTime":"2018-06-12T22:40:06.708Z",
"resourceLocation":"https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-b68a21fd-cdb3-41f1-a566-0772872a8a0c/teachers/teacher2@contoso.net",
"resourceId":"teacher2@contoso.net"
}
传输笔记本
若要在异步调用中将笔记本从一位教师传输到另一位教师，向 classNotebooks 端点发送 POST 请求。
POST ../classnotebooks/{notebook-id}/Microsoft.OneNote.Api.classnotebooktransfer
此 API 要求租户管理员特权。
在邮件正文中，使用传输课堂笔记本参数参数发送 JSON 对象。
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"alias@tenant"
},
"destinationNotebookName": "notebook-name"
}
}
| 参数 | 说明 |
|---|---|
| destinationNotebookName | 目标的笔记本名称。 |
| destinationTeacher | 主体对象。 |
| sourceTeacher | 主体对象。 |
源和目标教师由包含下列参数的主体对象代表。
| 参数 | 说明 |
|---|---|
| id | Office 365 用户主体名称。 若要了解有关用户和组的详细信息，请参阅 Azure AD 图形 API 文档。 |
| principalType | 人员 |
示例
以下示例传输名为 Math 101 的课堂笔记本。
请求
POST https://www.onenote.com/api/v1.0/me/notes/classnotebooks/1-9a43afaa-7dc9-4405-b661-b735ebf722a0/Microsoft.OneNote.Api.classnotebooktransfer
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
{
"ClassNotebookTransfer" : {
"sourceTeacher": {
"principalType":"Person",
"id":"teacher1@contososd.org"
},
"destinationTeacher" : {
"principalType":"Person",
"id":"teacher2@contososd.org"
},
"destinationNotebookName": "Math 101"
}
}
响应
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
轮询 Location 端点以获取传输笔记本的状态。
请求
GET https://www.onenote.com/api/v1.0/me/notes/operations/transfer-9a43afaa-7dc9-4405-b661-b735ebf722a0
响应
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"transfer9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}
更新成员资格
若要在异步调用更新课堂笔记本的成员资格，使用标头 Prefer: respond-async 向 classNotebooks 端点发送 POST 请求 。
POST
../groups/{groupId}/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
对于邮件正文和带更新成员资格操作参数的 JSON 对象，请参阅使用课堂笔记本中的更新成员资格一节。
示例
以下示例将同步统一组的默认课堂笔记本。
请求
POST https://www.onenote.com/api/v1.0/myOrganization/groups/1d13f814-83e5-4c11-8294-53bf40defd91/notes/classnotebooks/classnotebooks/Microsoft.OneNote.Api.UpdateMembership
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Prefer: respond-async
响应
HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
轮询 Location 端点以获取更新课堂笔记本成员资格的状态。
请求
GET https://www.onenote.com/api/v1.0/me/notes/operations/updatemembership-9a43afaa-7dc9-4405-b661-b735ebf722a0
响应
{
"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/operations/$entity",
"id":"updateMembership-9a43afaa-7dc9-4405-b661-b735ebf722a0",
"status":"completed",
"createdDateTime":"0001-01-01T00:00:00Z",
"lastActionDateTime":"0001-01-01T00:00:00Z",
"resourceId":"1-6e0cebcb-b589-4632-8b31-1ffe804652e0"
}