复制笔记本、分区和页面

项目
01/26/2016

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

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

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

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

备注

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

将页面复制到分区

../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 权限范围。

通过