在 OneNote 实体上创建共享链接

  • 项目

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

创建一个共享链接，以便与任何人共享 OneNote 文件。 您可以使用此API来创建，获取和撤销匿名访客链接。 访客链接将被授予编辑权限或仅查看权限，而无需登录。

GET ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink

POST ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

DELETE ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink

备注

共享链接支持 Office 365 个人、站点和组笔记本，但不支持 OneDrive 上的消费类笔记本。 此次，只有分区组实体在目前可获取支持。

构建请求 URI

  1. 若要构建请求 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/

  2. 接下来，将路径添加到分区组实体，然后添加共享链接功能。

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

https://www.onenote.com/api/v1.0/me/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

要为分区组创建匿名链接，请使用适当的端点发送 GET 请求。

GET ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink

函数参数 accessLevel 的枚举值表示共享链接的访问级别。

参数 accessLevel 枚举值 创建共享链接所需访问级别（查看或编辑）
View 创建到项目的只读链接。
Edit 创建到项目的读写链接。

示例

请求

GET ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink(accessLevel=Microsoft.OneNote.Api.SharingLinkAccessLevel'View') 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

响应

HTTP/1.1 200 Ok

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Edm.String",
  "value":"https://www.contoso.com/_layouts/15/WopiFrame.aspx?folderid=084a6fcc95ab54a678257e1b9cba41e7e&authkey=AXXriBu-O475sT4tfJeJDkA&FixProgId=1"
}

请求和响应信息

以下信息适用于 Get /GetAnonymousSharingLink 请求。

请求数据 说明
协议 所有请求均使用 SSL/TLS HTTPS 协议。
授权标头 Bearer {token}，其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。

如果缺少或无效，则请求失败，并显示 401 状态代码。 请参阅使用 Azure AD 进行身份验证（企业应用程序）。
权限范围 Notes.ReadWrite 或 Notes.ReadWrite.All


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

按照以下步骤获取现有链接或创建一个不存在的链接。 匿名链接可用于在不登录的情况下查看OneNote文件。

POST ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

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

参数 accessLevel 枚举值 创建共享链接所需访问级别（查看或编辑）
视图 创建到项目的只读链接。
编辑 创建到项目的读写链接。

示例

请求

POST ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

响应

HTTP/1.1 200 Ok

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Edm.String",
  "value":"https://www.contoso.com/_layouts/15/WopiFrame.aspx?folderid=084a6fcc95ab54a678257e1b9cba41e7e&authkey=AXXriBu-O475sT4tfJeJDkA&FixProgId=1"
}

请求和响应信息

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

请求数据 说明
协议 所有请求均使用 SSL/TLS HTTPS 协议。
授权标头 Bearer {token}，其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。

如果缺少或无效，则请求失败，并显示 401 状态代码。 请参阅使用 Azure AD 进行身份验证（企业应用程序）。
权限范围 Notes.ReadWrite 或 Notes.ReadWrite.All


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

按照步骤撤销分区组的现有共享链接。

DELETE ../v1.0/me/notes/sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink

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

参数 accessLevel 枚举值 创建共享链接所需访问级别（查看或编辑）
视图 创建到项目的只读链接。
编辑 创建到项目的读写链接。

示例

请求

DELETE ../v1.0/me/notes/sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink
Authorization: Bearer {token}
Accept: application/json

{ 
  “accessLevel”: “view” 
}

响应

HTTP/1.1 204 No Content

请求和响应信息

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

请求数据 说明
协议 所有请求均使用 SSL/TLS HTTPS 协议。
授权标头 Bearer {token}，其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。

如果缺少或无效，则请求失败，并显示 401 状态代码。 请参阅使用 Azure AD 进行身份验证（企业应用程序）。
权限范围 Notes.ReadWrite 或 Notes.ReadWrite.All


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

打开或关闭 SharePoint Online 环境的外部共享

管理 SharePoint Online 环境的外部共享

构造 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 关键字访问。

Office 365 组笔记本

Office 365 组是 Office 365 互连体验的一部分。 组成员可以共享笔记本、文件和电子邮件。

对当前用户所属指定组中的 OneNote 内容使用 myOrganization/groups/{id}。 Office 365 组（返回统一 groupType）是唯一受支持的组类型。 使用 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 仅适用于已编制索引的站点。 为新站点建立索引可能需要几个小时。

另请参阅