使用员工笔记本

项目
07/26/2016

适用于：Office 365 上的企业笔记本

世界各地的中小学校、学院和大学都在使用员工笔记本，帮助促进生产力、促进参与和增进协作。

您可以使用 staffNotebooks 端点为员工笔记本执行通用任务，例如创建员工笔记本和添加或删除领导或成员。

备注

OneNote API提供针对员工笔记本特定操作的 staffNotebooks 端点。

构建请求 URI

若要构建请求 URI，请从平台的服务根 URL 开始：

OneDrive 商业版上的笔记本

https://www.onenote.com/api/v1.0/me/notes/

https://www.onenote.com/api/v1.0/users/{id}/notes/

SharePoint 网站笔记本

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

统一组笔记本

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/
然后，附加 staffNotebooks端点，并根据需要在后面附加资源路径：

创建员工笔记本

../staffNotebooks[?omkt,sendemail]

更新员工笔记本

../staffNotebooks/{notebook-id}

获取一个或多个员工笔记本

../staffNotebooks

../staffNotebooks/{notebook-id}

删除员工笔记本

../staffNotebooks/{notebook-id}

添加成员或领导

../staffNotebooks/{notebook-id}/members

../staffNotebooks/{notebook-id}/leaders

删除成员或领导

../staffNotebooks/{notebook-id}/members/{member-id}

../staffNotebooks/{notebook-id}/leaders/{leader-id}

插入部分

../staffNotebooks/{notebook-id}/copySectionsToContentLibrary

您的完整请求 URI 应当类似如下示例：

https://www.onenote.com/api/v1.0/me/notes/staffNotebooks/{id}/leaders/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/staffNotebooks/{id}/members

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/staffNotebooks

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/staffNotebooks/{id}

https://www.onenote.com/api/v1.0/me/notes/staffNotebooks/{id}/copySectionsToContentLibrary

备注

了解有关服务根 URL 的详细信息。

创建员工笔记本

要创建员工笔记本，发送一个POST请求到staffNotebooks端点。

POST ../staffNotebooks[?omkt,sendemail]

在消息正文中，发送带有员工笔记本创建参数的JSON对象。

{
    "name": "notebook-name",
    "memberSections": [ 
        "section1-name", 
        "section2-name"
    ],
    "leaders": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
    ],
    "members": [
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group" 
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        },
        {
            "id": "alias@tenant",
            "principalType": "Person-or-Group"
        }
   ], 
   "hasLeaderOnlySectionGroup": true
}

参数	说明
name	笔记本的名称。
memberSections	包含一个或多个模块名称的数组。这些模块在每个成员的模块组中创建。
领导者	包含一个或多个主体对象的数组。
成员	包含一个或多个主体对象的数组。为每个成员创建一个模块分组。
hasLeaderOnlySectionGroup	`true` 创建一个仅限领导者有权查看的模块分组。
omkt	指定笔记本语言的 URL 查询参数。默认值为 `en-us`。示例： `?omkt=es-es`
sendemail	URL 查询参数，用于指定创建笔记本时是否向分配笔记本的领导者和员工发送电子邮件通知。默认值为 `false`。

领导者和成员由主体对象表示，包含以下属性：

参数	说明
id	Office 365 用户主体名称。参阅 Azure AD Graph API 文档，了解关于用户和分组的更多信息。
principalType	`Person` 或 `Group`

支持的语言

您可以使用 omkt={language-code} URL 查询参数，创建特定语言的员工笔记本。例如：

POST ../staffNotebooks?omkt=de-de

支持以下语言代码。默认为en-us。

代码	语言
bg-bg	保加利亚语（保加利亚）
cs-cz	捷克语 (捷克共和国)
da-dk	丹麦语 (丹麦)
de-de	德语(德国)
el-gr	希腊语（希腊）
en-us	英语(美国)
es-es	西班牙语(西班牙)
et-ee	爱沙尼亚语（爱沙尼亚）
fi-fi	芬兰语(芬兰)
fr-fr	法语(法国)
hi-in	印地语（印度）
hr-hr	克罗地亚语（克罗地亚）
hu-hu	匈牙利语(匈牙利)
id-id	印尼语（印度尼西亚）
it-it	意大利语 (意大利)
ja-jp	日本语（日本）
kk-kz	哈萨克语（哈萨克斯坦）
ko-kr	朝鲜语（韩国）
lt-lt	立陶宛语(立陶宛)
lv-lv	拉脱维亚语(拉脱维亚)
ms-my	马来语 (东南亚)
nb-no	挪威语 (挪威)
nl-nl	荷兰语(荷兰)
pl-pl	波兰语 (波兰)
pt-br	葡萄牙语 (巴西)
pt-pt	葡萄牙语(葡萄牙)
ro-ro	罗马尼亚语(罗马尼亚)
ru-ru	俄语（俄罗斯）
sk-sk	斯洛伐克语(斯洛伐克共和国)
sl-si	斯洛文尼亚语(斯洛文尼亚)
sr-Latn-RS	塞尔维亚语 (塞尔维亚和黑山共和国)
sv-se	瑞典语（瑞典）
th-th	泰语（泰国）
tr-tr	土耳其语（土耳其）
uk-ua	乌克兰语（乌克兰）
vi-vn	越南语 (越南)
zh-cn	简体中文（中国）
zh-tw	繁体中文（台湾）

示例

以下请求会创建一个名为 员工会议的员工笔记本。

POST ../v1.0/users/{leader-id}/notes/staffNotebooks?sendemail=true
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "name": "Staff Meetings",
    "memberSections": [
        "Staff Notes",
        "Meeting Summaries",
    ],
    "leaders": [
        {
            "id": "leader1@contoso.com",
            "principalType": "Person"
        }
    ],
    "members": [
        {
            "id": "member1@contoso.com",
            "principalType": "Person"
        },
        {
            "id": "member2@contoso.com",
            "principalType": "Person" 
        },
        {
            "id": "member3@contoso.com",
            "principalType": "Person"
        },
        {
            "id": "member4@contoso.com",
            "principalType": "Person"
        }
    ],
    "hasLeaderOnlySectionGroup": true
}

这将创建一个带有四个成员分组的员工笔记本，每个分组都包含一个讲义、员工注释和会议摘要部分。为每个成员创建的分组仅限成员和领导者访问。它也创建一个 仅限领导者 分组，仅限领导者访问。查询参数指定在创建笔记本时向领导人和成员发送电子邮件通知。sendemail=true

请求和响应信息

以下信息适用于POST /staffNotebooks请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
Content-Type 标头	`application/json`
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	201 HTTP 状态代码。
响应正文	JSON 格式的新笔记本 OData 表示。除常规笔记本属性外，员工笔记本也具有以下属性： memberSections。笔记本中的成员部分。领导者。可以访问笔记本的领导者。成员。可以访问笔记本的成员。 hasLeaderOnlySectionGroup。 `true` 否则，笔记本包含仅限领导者分组`false`。
错误	如果请求失败，API 将在响应正文的 @api.diagnostics 对象中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

更新员工笔记本

要更新员工笔记本，请发送PATCH请求至 staffNotebooks / {笔记本-ID} 端点。

备注

目前，只有 hasTeacherOnlySectionGroup 属性可以在 PATCH 请求中更新。

PATCH ../staffNotebooks/{notebook-id}

在消息正文中，发送带有更新参数的 JSON 对象。

{
    "hasLeaderOnlySectionGroup": true
}

参数	说明
hasLeaderOnlySectionGroup	`true` 添加一个仅限领导人有权查看的模块分组。 `false`			UNTRANSLATED_CONTENT_START			is not supported.			UNTRANSLATED_CONTENT_END

查看这些方法通过其他方式更换员工笔记本：添加成员或领导者、删除成员或领导、插入模块。

示例

以下请求将 仅限领导者 分组添加到指定的员工笔记本。

PATCH ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id}
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "hasLeaderOnlySectionGroup": true
}

新的 仅限领导者 模块分组仅限领导者查看。

请求和响应信息

以下信息适用于PATCH ../staffNotebooks/{notebook-id}请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
Content-Type 标头	`application/json`
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	204 HTTP 状态代码。
错误	如果请求失败，则 API 在响应正文中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

获取员工笔记本

要获得一个或多个员工笔记本，请发送一个GET请求给 staffNotebooks 端点。

获取一个或多个员工笔记本

GET ../staffNotebooks[?filter,orderby,select,top,skip,expand,count]

获取特定的员工笔记本

GET ../staffNotebooks/{notebook-id}[?select,expand]

笔记本可以扩展 leaders 和 members 属性。默认排序顺序是 name asc。

员工笔记本也返回GET /notebooks请求，但结果将不包含任何员工笔记本特定的属性。

示例

以下请求获取自 2016 年 1 月 1 日起创建的员工笔记本。

GET ../v1.0/users/{leader-id}/notes/staffNotebooks?filter=createdTime%20ge%202016-01-01 
Authorization: Bearer {token}
Accept: application/json

若要了解有关获取笔记本的更多信息，包括支持的查询字符串选项和示例，请参阅获取 OneNote 内容和结构。

请求和响应信息

以下信息适用于GET /staffNotebooks请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
接受标头	`application/json`
权限范围	Notes.Read， Notes.ReadWrite.CreatedByApp， Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	200 HTTP 状态代码。
响应正文	JSON 格式的员工笔记本 OData 表示。除常规笔记本属性外，员工笔记本也具有以下属性： memberSections。笔记本中的成员部分。领导者。可以访问笔记本的领导者。成员。可以访问笔记本的成员。 hasLeaderOnlySectionGroup。 `true` 否则，笔记本包含仅限领导者分组`false`。
错误	如果请求失败，API 将在响应正文的 @api.diagnostics 对象中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

删除员工笔记本

要删除员工笔记本，请发送DELETE请求给 staffNotebooks / {笔记本-ID} 端点。

DELETE ../staffNotebooks/{notebook-id}

示例

以下请求删除指定的员工笔记本。

DELETE ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id} 
Authorization: Bearer {token}
Accept: application/json

请求和响应信息

以下信息适用于DELETE ../staffNotebooks/{notebook-id}请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	204 HTTP 状态代码。
错误	如果请求失败，则 API 在响应正文中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

添加成员和领导者

增加领导者和成员，并给予员工笔记本访问权限。添加成员，同时创建成员分组。此分组仅限成员和领导者访问，并包含为笔记本定义的成员部分。

要将成员或领导者添加到员工笔记本中，请向相应的端点发送POST请求。

添加成员

POST ../staffNotebooks/{notebook-id}/members

添加领导者

POST ../staffNotebooks/{notebook-id}/leaders

在消息正文中发送一个 JSON 主体对象。您可以为每个请求添加一位成员或一位领导者。

{
    "id": "alias@tenant",
    "principalType": "Person-or-Group"
}

领导者和成员由主体对象表示，包含以下属性：

参数	说明
id	Office 365 用户主体名称。参阅 Azure AD Graph API 文档，了解关于用户和分组的更多信息。
principalType	`Person` 或 `Group`

示例

以下请求将领导者添加到指定的员工笔记本。

POST ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id}/leaders 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "id": "leader2@contoso.com",
    "principalType": "Person"
}

请求和响应信息

以下信息适用于POST /members和POST /leaders 请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
Content-Type 标头	`application/json`
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	201 HTTP 状态代码。
响应正文	已添加的成员或领导者。
错误	如果请求失败，API 将在响应正文的 @api.diagnostics 对象中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

删除成员和领导者

从员工笔记本中删除成员和领导者撤销他们对笔记本的访问权限，但不删除任何内容。

要将成员或领导者从员工笔记本中移除，请向相应的端点发送DELETE 请求。

删除成员

DELETE ../staffNotebooks/{notebook-id}/members/{member-id}

删除领导者

DELETE ../staffNotebooks/{notebook-id}/leaders/{leader-id}

您可以通过单个请求删除一位成员或一位领导者。

示例

以下请求从指定的员工笔记本中删除指定的成员。

DELETE ../v1.0/users/{leader-id}/notes/staffNotebooks/{notebook-id}/members/{member-id} 
Authorization: Bearer {token}
Accept: application/json

请求和响应信息

以下信息适用于DELETE /members和DELETE /leaders 请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	204 HTTP 状态代码。
错误	如果请求失败，API 将在响应正文的 @api.diagnostics 对象中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

插入模块

使用copySectionsToContentLibrary ，从 Office 365 笔记本复制特定模块，并将其插入员工笔记本的内容库。内容库是员工笔记本中的一个分组，该分组设定为领导者的读/写权限和成员的读取权限。

若要将模块插入员工笔记本，请向目标员工笔记本的copySectionsToContentLibrary端点发送 POST 请求。例如：

POST ../staffNotebooks/{notebook-id}/copySectionsToContentLibrary

在消息正文中，发送带有sectionIds参数的 JSON 对象。

{
    "sectionIds": [
        "section1-id", 
        "section2-id",
        ...
    ]
}

参数	说明
sectionIds	包含要插入员工笔记本的模块 ID 的数组。

用户必须有权访问目标模块和笔记本（拥有或共享）。所有目标必须在同一个租户中。

示例

以下请求将两个模块插入到指定员工笔记本的内容库。

POST ../v1.0/me/notes/staffNotebooks/{notebook-id}/copySectionsToContentLibrary
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "sectionIds": [
        "1-85ba33b1-4959-4102-8dcd-d98e4e56e56f", 
        "1-8ba42j81-4959-4102-8dcd-d98e4e94s62ef"
    ]
}

请求和响应信息

以下信息适用于POST /copySectionsToContentLibrary请求。

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	`Bearer {token}`，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用程序）进行身份验证。
Content-Type 标头	`application/json`
接受标头	`application/json`
权限范围	Notes.ReadWrite.CreatedByApp，Notes.ReadWrite，或 Notes.ReadWrite.All

响应数据	说明
成功代码	201 HTTP 状态代码。
错误	如果创建请求失败，则 API 在响应正文中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。在与 Microsoft 支持部门协作来解决问题时，可以使用此值和日期标头值。

构造 OneNote 服务根 URL

OneNote 服务根 URL 为 OneNote API 的所有调用使用以下格式。

https://www.onenote.com/api/{version}/{location}/notes/

URL 中的 version 部分表示要使用的 OneNote API 的版本。

|||UNTRANSLATED_CONTENT_START|||Use v1.0 for stable production code.|||UNTRANSLATED_CONTENT_END|||
用于试用正在开发的功能。beta Beta 版中的特性和功能可能会有所更改，因此，不应将其用于生产代码。

URL 中的 location 部分表示要访问的笔记本的位置：

OneDrive for Business 上的笔记本
- 对于当前用户拥有的 OneNote 内容，使用 me。
- 为指定用户已与当前用户共享的 OneNote 内容（此 URL 中）使用 users/{id}。使用 Azure AD Graph API 可获取用户 ID。
SharePoint 网站笔记本
- Team 网站和其他 SharePoint 网站可以在其文档库中包含 OneNote 笔记本。
- 对于当前用户登录的租户网站上的 OneNote 内容，请使用 myOrganization/siteCollections/{id}/sites/{id}。仅支持当前租户，使用 myOrganization 关键字访问。了解如何获得网站 ID。
统一组笔记本
- 统一组（也称为 Office 365 组）是连接的 Office 365 体验的一部分。组成员可以共享笔记本、文件和电子邮件。
- 使用于当前用户所属指定组中的 OneNote 内容 myOrganization/groups/{id}。统一组是唯一支持的组类型。使用 Azure AD Graph API 可获取组 ID。

使用 FromUrl 方法获取网站集和网站 ID

可以使用 FromUrl 方法获取指定的绝对站点 URL 的网站集和网站 ID。应该仅在需要时进行此调用，然后存储这些值以供将来使用。

站点 URL 的格式取决于配置，例如 https://domain.sharepoint.com/site-a 或 https://domain.com/sites/site-a。

示例请求

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

响应示例

{"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata", "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5", "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"}

使用 FromUrl 并使用 SharePoint 网站的笔记本的要求：

只能在具有默认文档库的站点上创建 OneNote 笔记本、节组、节和页面。（某些网站模板不会创建默认文档库。）但是，GET 请求会从网站上的所有文档库返回 OneNote 内容。
OneNote 服务根 URL 是不可变的，这意味着不能使用 SharePoint REST API 网站路径然后向其添加 notes 端点。
您代其访问的用户必须是该站点的成员。
FromUrl 仅适用于已编制索引的站点。为新站点建立索引可能需要几个小时。

通过

使用员工笔记本

构建请求 URI

创建员工笔记本

支持的语言

示例

请求和响应信息

更新员工笔记本

示例

请求和响应信息

获取员工笔记本

示例

请求和响应信息

删除员工笔记本

示例

请求和响应信息

添加成员和领导者

示例

请求和响应信息

删除成员和领导者

示例

请求和响应信息

插入模块

示例

请求和响应信息

构造 OneNote 服务根 URL

使用 FromUrl 方法获取网站集和网站 ID

示例请求

响应示例

另请参阅

其他资源