使用异步课堂笔记本

项目
08/21/2018

适用于：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"
}

另请参阅

使用课堂笔记本

通过