复制笔记本、分区和页面

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

要复制 OneNote 笔记本、分区或页面，需向相应的复制操作端点发送 POST 请求。 例如：

POST ../notes/sections/{id}/copyToNotebook

在消息正文中发送一个 JSON 复制对象。 如果请求成功，OneNote API 会返回一个 202 HTTP 状态代码和一个 Operation-Location 标头。 之后，你可以轮询操作端点的结果。

备注

复制功能当前受 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. 附加相应的复制操作端点：

   将页面复制到分区

   ../pages/{id}/copyToSection

   将分区复制到笔记本

   ../sections/{id}/copyToNotebook

   将分区复制到分区组

   ../sections/{id}/copyToSectionGroup

   复制笔记本

   ../notebooks/{id}/copyNotebook

笔记本被复制到目标文档库中的“笔记本”文件夹。 如果“笔记本”文件夹不存在，则会创建。

完整的请求 URI 类似于以下示例之一：

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

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

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

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

备注

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

构造邮件正文

在消息正文中，发送一个包含操作所需参数的 JSON 对象。 如果不需要参数，可以发送空的正文。

参数	说明
ID	目标笔记本或分区组的 ID（用于分区）；或目标分区的 ID（用于页面）。 仅与 copyToNotebook、copyToSectionGroup 和 copyToSection 一起使用。
siteCollectionId	包含项目将要复制到的目标站点的 SharePoint 网站集 ID。 与 siteId 一起使用，且仅在复制到 SharePoint 网站时使用。
siteId	项目将要复制到的 SharePoint 网站的 ID。 与 siteCollectionId 一起使用，且仅在复制到 SharePoint 网站时使用。
groupId	项目将要复制到的组的 ID。 仅在复制到统一组时使用。
renameAs	副本的名称。 仅与 copyNotebook、copyToNotebook 和 copyToSectionGroup 一起使用。 默认为现有项目的名称。

学习如何获取笔记本、分区组和分区 ID，以及如何获取网站集和网站 ID。 有关获取组 ID 的信息，请参阅 Azure AD Graph API 文档。

复制操作的示例流程

首先向要复制的项目发送一个 POST 请求给复制操作。 只要源和目标位于同一租户，你就可以从用户有权访问（拥有或共享）的笔记本中复制。

以下示例将个人笔记本复制到 SharePoint 团队网站。 该请求不包括 renameAs 参数，所以新笔记本使用现有名称。

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

备注

复制操作会遵守源笔记本的权限，因此经过身份验证的用户必须能够访问源笔记本才能对其进行复制。 但是，副本不保留源的权限。 该副本具有权限，就好像用户刚创建它一样。

如果调用成功，OneNote API 会返回一个 202 状态代码和一个 Operation-Location 标头。 以下是回复的摘录：

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

然后轮询 Operation-Location 端点，获取复制操作的状态：

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

OneNote API 返回一个显示当前状态的 OperationModel 对象。 状态完成时返回以下示例响应。

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

状态可以是已完成、正在运行或失败。

• 如果是已完成，resourceLocation 属性将包含新副本的资源端点。
• 如果是正在运行，percentComplete 属性将显示完成的大致百分比。
• 如果是失败，error 和 @ api.diagnostics 属性将提供错误信息。

你可以轮询操作端点，直到操作完成或失败。

请求和响应信息

请求数据	说明
协议	所有请求均使用 SSL/TLS HTTPS 协议。
授权标头	Bearer {token}，其中 {token} 是有效的 OAuth 2.0 访问令牌，用于您注册的应用。 如果丢失或无效，请求将失败，并显示 401 状态代码。 请参阅身份验证和权限。
Content-Type 标头	application/json
接受标头	application/json

响应数据	说明
成功代码	202 状态 HTTP 状态码。
Operation-Location 标头	用于轮询操作状态的 URL。 轮询操作端点将返回一个包含操作状态和其他信息的 OperationModel 对象。
X-CorrelationId 标头	唯一标识该请求的 GUID。 在与 Microsoft 支持部门协作来解决问题时，可以使用此值和日期标头值。

构造 OneNote 服务根 URL

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

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

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

• 使用 v1.0 获得稳定的生产代码。

• 用于试用正在开发的功能。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 仅适用于已编制索引的站点。 为新站点建立索引可能需要几个小时。

权限

要复制 OneNote 笔记本、分区和页面，您需要请求适当的权限。 选择应用完成其工作所需的最低级别的权限。

平台	权限范围
消费者	office.onenote_create、office.onenote_update_by_app、office.onenote_update
企业版	Notes.Create、Notes.ReadWrite.CreatedByApp、Notes.ReadWrite、Notes.ReadWrite.All

有关权限范围及其工作方式的详细信息，请参阅 OneNote 权限范围。

另请参阅

• 获取 OneNote 内容和结构
• 创建 OneNote 页
• OneNote 开发
• OneNote 开发中心
• OneNote 开发者博客
• 关于 Stack Overflow 的 OneNote 开发问题
• OneNote GitHub 存储库