管理 OneNote 实体的权限

项目
05/24/2016

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

您可以使用权限端点来管理对笔记本，分区组和分区的读取或写入权限。

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

备注

Office 365 个人、网站和统一组笔记本支持管理权限，但 OneDrive 上的消费类笔记本不支持管理权限。

构建请求 URI

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

OneDrive for Business 上的笔记本

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/
然后，将路径添加到目标笔记本、分区组或分区实体，随后添加权限或权限/ {id} 端点。

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

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

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

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

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

备注

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

创建或更新权限

如需创建或更新笔记本、分区组或分区的权限，请向适当的端点发送 POST 请求。您仅可以为每个请求创建或更新一次权限。

权限适用于继承链上的所有 OneNote 实体。

您可以通过更新权限来授予更高级别的访问权限。但是，如需限制访问权限，您必须删除现有权限并创建新权限。参见权限继承和优先权。

创建或更新笔记本的权限

POST ../notebooks/{notebook-id}/permissions

创建或更新分区组的权限

POST ../sectiongroups/{sectiongroup-id}/permissions

创建或更新分区的权限

POST ../sections/{section-id}/permissions

在消息正文中，发送一个带有必要参数的 JSON 对象。

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}

参数	说明
userRole	权限类型：`Owner`、`Contributor`，或`Reader`。
userId	被分配权限的用户或组登录。该 API 接受包含成员资格提供者名称的声明格式 (`i:0#.f\|membership\|username@domainname.com`)，或仅包含用户的主要登录名 (`username@domainname.com`)。

示例

以下请求会为指定的笔记本创建权限。

请求

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

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

响应

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

请求和响应信息

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

请求数据说明

协议所有请求均使用 SSL/TLS HTTPS 协议。

授权标头

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

Bearer {token}，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。

如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用）进行身份验证。

权限范围 Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, 或 Notes.ReadWrite.All

响应数据	说明
成功代码	201 HTTP 状态代码。
响应正文	JSON 格式权限的 OData 表示法。参见获取权限了解关于Permission对象的描述。
错误	如果请求失败，则 API 在响应正文中返回错误。
X-CorrelationId 标头	唯一标识该请求的 GUID。使用 Microsoft 支持来解决问题时，您可以使用此值以及 Date 标头的值。

获取权限

如需获取笔记本、分区组或分区的权限，请向适当的端点发送 GET 请求。

获取笔记本的权限

GET ../notebooks/{notebook-id}/permissions

获取笔记本的特定权限

GET ../notebooks/{notebook-id}/permissions/{permission-id}

获取分区组的权限

GET ../sectiongroups/{sectiongroup-id}/permissions

获取分区组的特定权限

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

获取分区的权限

GET ../sections/{section-id}/permissions

获取分区的特定权限

GET ../sections/{section-id}/permissions/{permission-id}

GET 请求可返回目标实体上用户角色的最高权限。如需了解更多信息，请参阅权限继承和优先权。

GET /permissions 请求支持 OData 查询选项，如下所示：

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

GET ../permissions/{permission-id}[?select]

备注

该权限端点不支持 expand 查询选项。

如需了解有关获取OneNote实体的更多信息（包括支持的查询字符串选项和示例），请参阅获取 OneNote 内容和结构。

Permission 对象

权限包含以下属性。

属性	说明
名称	用户或组主体的显示名称。示例： `"name":"Everyone"`
id	表单中的唯一权限标识符 `1-{principal-member-id}`。示例： `"id":"1-4"`
self	权限对象的 URL。
userId	被分配权限的用户或组登录。此值始终以声明格式返回，例如：`i:0#.f\|membership\|username@domainname.com`。
userRole	权限类型：`Owner`、`Contributor`，或`Reader`。

示例

以下请求可获取指定笔记本的所有权限。

请求

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

响应

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

请求和响应信息

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

请求数据说明

协议所有请求均使用 SSL/TLS HTTPS 协议。

授权标头

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

Bearer {token}，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。

如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用）进行身份验证。

权限范围 Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, 或 Notes.ReadWrite.All

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

删除权限

如需删除笔记本、分区组或分区的权限，请向适当的端点发送 DELETE 请求。您通过每次请求可以删除一项权限。

当您删除某项权限时，继承链上的所有 OneNote 实体的该权限将被删除。

删除笔记本的权限

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

删除分区组的权限

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

删除分区的权限

DELETE ../sections/{section-id}/permissions/{permission-id}

示例

以下请求会删除指定笔记本的权限。

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

请求和响应信息

以下信息适用于DELETE /permissions请求。

请求数据说明

协议所有请求均使用 SSL/TLS HTTPS 协议。

授权标头

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

Bearer {token}，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。

如果丢失或无效，请求将失败并显示 401 状态代码。请参阅使用 Azure AD（企业应用）进行身份验证。

权限范围 Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, 或 Notes.ReadWrite.All

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

权限、继承和优先级

您可以为笔记本，分区组和分区设置以下权限。

权限	说明
读者	以只读方式访问笔记本、分区组和分区。
参与者	可以添加、编辑和删除笔记本、分区组和分区。
Owner	上述所有权限也可以管理权限（获取、创建和删除）。

在管理 OneNote 实体的权限时，您应该了解权限继承和优先级。

继承。实体可继承其父级的权限。所以，笔记本可继承包含笔记本的文档库的权限。而这些权限又由笔记本内的子分区组和分区继承。当您在笔记本、分区组或分区上设置显式权限时，权限也会传播到其子对象。
优先级。当 OneNote 实体上被设置了彼此冲突的权限时，以最高（最高级）权限为准。当多项权限被应用于某个实体时（显式或继承）或用户或组属于多个角色时，用户和组可能会被授予彼此冲突的访问权限。

这些原则决定了OneNote API如何管理权限。例如：

当您为笔记本或分区组创建某项权限时，该权限会被推送给所有子对象。
当您删除笔记本或分区组的权限时，所有子对象的该权限也会被删除。
当您获得权限时，OneNote API 仅返回拥有冲突权限的角色的最高权限。
您可以更新权限，以便为用户或用户组授予更高权限。但是，如果您想限制访问权限，您必须先删除较高的权限，然后通过限制访问权限创建新权限。

这是因为， POST /permissions 请求实际上会将用户角色附加到实体的权限集合中，并且以最高访问权限为准。换言之，您可以通过更新Reader访问权限来授予参与者或所有者访问权限，但是您无法通过更新参与者权限仅授予读者访问权限。

构造 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 笔记本。
- 使用 myOrganization/siteCollections/{id}/sites/{id} OneNote 中的内容中的当前用户登录到租户的网站。仅支持当前租户，使用 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 仅适用于已编制索引的站点。为新站点建立索引可能需要几个小时。

通过

管理 OneNote 实体的权限

构建请求 URI

创建或更新权限

示例

请求

响应

请求和响应信息

获取权限

Permission 对象

示例

请求

响应

请求和响应信息

删除权限

示例

请求和响应信息

权限、继承和优先级

构造 OneNote 服务根 URL

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

示例请求

响应示例

另请参阅

其他资源