创建 OneNote 页Create OneNote pages

适用于:OneDrive 上的消费者笔记本 | Office 365 上的企业级笔记本Applies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

若要创建 OneNote 页面,请向 pages 终结点发送一个 POST 请求。To create a OneNote page, you send a POST request to a pages endpoint. 例如:For example:

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


发送在邮件正文中定义页面的 HTML。Send the HTML that defines the page in the message body. 如果请求成功,Microsoft Graph 将返回 201 HTTP 状态代码。If the request is successful, Microsoft Graph returns a 201 HTTP status code.

注意: 若要了解有关可以发送以创建节、节组和笔记本的 POST 请求,请参阅我们的交互式 REST 参考Note: To learn about the POST requests you can send to create sections, section groups, and notebooks, see our interactive REST reference.

构建请求 URIConstruct the request URI

若要构建 POST 请求 URI,请从服务根 URL 开始:To construct the POST request URI, start with the service root URL:

https://graph.microsoft.com/v1.0/me/onenote


然后追加页面终结点:Then append the pages endpoint:

  • 在任何节中创建页面(由节名称指定)Create a page in any section (specified by section name)

    .../pages?sectionName=DefaultSection

  • 在任何节中创建页面(由 ID 指定)Create a page in any section (specified by ID)

    .../sections/{section-id}/pages

如果要在用户的个人笔记本中创建页面,Microsoft Graph 还提供了可用于在默认笔记本中创建页面的终结点:If you're creating pages in the user's personal notebook, Microsoft Graph also provides endpoints you can use to create pages in the default notebook:

  • 在默认笔记本的默认节中创建页面Create a page in the default section of the default notebook

    ../pages

完整的请求 URI 类似于以下示例之一:Your full request URI will look like one of these examples:

  • https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework

了解有关服务根 URL 的详细信息。Learn more about the service root URL.

使用 sectionName URL 参数Using the sectionName URL parameter

使用 sectionName 参数在默认笔记本的命名节中创建页面时,适用以下规则:The following rules apply when using the sectionName parameter to create a page in a named section in the default notebook:

  • 仅顶级节可以引用(不是节组中的节)。Only top-level sections can be referenced (not sections within section groups).

  • 如果默认笔记本中不存在带指定名称的节,API 将自动创建该节。If a section with the specified name doesn't exist in the default notebook, the API creates it. 这些字符不允许出现在节名称中:? * \ / : < > | & # " % ~These characters are not allowed for section names: ? * \ / : < > | & # " % ~

  • 出于匹配原因,节名称不区分大小写,但创建节时要保留大小写。Section names are case-insensitive for matching, but case is preserved when sections are created. 因此,“My New Section”将以此方式显示,但“my new section”也会在后面的文章中匹配。So "My New Section" will display like that, but "my new section" would also match on subsequent posts.

  • 节名称必须为 URL 编码。Section names must be URL-encoded. 例如,空格必须编码为 %20For example, spaces must be encoded as %20.

  • SectionName 参数仅对../notes/pages路由(不是 ../notes/sections/{id}/pages)有效。The sectionName parameter is valid only with the ../notes/pages route (not ../notes/sections/{id}/pages).

由于如果不存在节便会进行创建,因此在应用创建的每一个页面上使用此调用都是安全的。Because sections are created if they don't exist, it's safe to use this call with every page your app creates. 用户可以重命名节,但 API 将创建一个使用你所提供的 sectionName 的新分区。Users might rename sections, but the API will create a new section with the section name that you supply.

注意: API 针对重命名节中的页面返回的链接仍然会到达那些旧页面。Note: The links returned by the API for pages in a renamed section will still reach those older pages.

构造邮件正文Construct the message body

定义页面内容的 HTML 被称为输入 HTMLThe HTML that defines page content is called input HTML. 输入 HTML 支持标准 HTML 和 CSS 子集,并增添了自定义属性。Input HTML supports a subset of standard HTML and CSS, with the addition of custom attributes. data-iddata-render-src 等自定义属性在输入和输出 HTML 中进行了说明。)(Custom attributes, like data-id and data-render-src, are described in Input and output HTML.)

在 POST 请求的邮件正文中发送输入 HTML。Send the input HTML in the message body of the POST request. 你可以使用 application/xhtml+xmltext/html 内容类型直接在邮件正文中发送输入 HTML,也可以在多部分请求的“演示文稿”部件中发送它。You can send the input HTML directly in the message body using the application/xhtml+xml or text/html content type, or you can send it in the "Presentation" part of a multipart request.

以下示例直接在邮件正文中发送输入 HTML。The following example sends the input HTML directly in the message body.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: application/xhtml+xml

<!DOCTYPE html>
<html>
  <head>
    <title>A page with a block of HTML</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>This page contains some <i>formatted</i> <b>text</b> and an image.</p>
    <img src="https://..." alt="an image on the page" width="500" />
  </body>
</html>

如果要发送二进制数据,则必须使用多部分请求If you're sending binary data, you must use a multipart request.

注意: 为简化编程和应用的一致性,可以使用多部分请求来创建所有页面。Note: To simplify programming and consistency in your app, you can use multipart requests to create all pages. 最好使用库来构造多部分邮件。It's a good idea to use a library to construct multipart messages. 这样可减少创建格式不正确的有效负载的风险。This reduces the risk of creating malformed payloads.

POST 页面请求中有关输入 HTML 的要求和限制Requirements and limitations for input HTML in POST pages requests

发送输入 HTML 时,请注意这些常规要求和限制:When sending input HTML, be aware of these general requirements and limitations:

  • 输入 HTML 应为 UTF-8 编码且格式标准的 XHTML。Input HTML should be UTF-8 encoded and well-formed XHTML. 所有容器开始标记都要求匹配结束标记。All container start tags require matching closing tags. 所有属性值必须使用双引号或单引号引住。All attribute values must be surrounded by double- or single-quote marks.

  • JavaScript 代码、包含的文件和 CSS 会被删除。JavaScript code, included files, and CSS are removed.

  • HTML 表单将全部删除。HTML forms are removed in their entirety.

  • Microsoft Graph 支持 HTML 元素的子集Microsoft Graph supports a subset of HTML elements.

  • Microsoft Graph 支持常见 HTML 属性的子集和一组自定义属性,如用于更新页面的 data-id 属性。Microsoft Graph supports a subset of common HTML attributes and a set of custom attributes, such as the data-id attribute used for updating pages. 有关受支持的属性,请参阅输入和输出 HTMLFor supported attributes, see Input and output HTML.

OneNote 页面受支持的 HTML 和 CSSSupported HTML and CSS for OneNote pages

并非所有元素、特性和属性都受支持(在 HTML4、XHTML、CSS、HTML5 等中)。Not all elements, attributes, and properties are supported (in HTML4, XHTML, CSS, HTML5, etc.). 相反,Microsoft Graph 接受一组有限的 HTML,以更好地适应用户使用 OneNote 的方式。Instead, Microsoft Graph accepts a limited set of HTML that better fits how people use OneNote. 有关详细信息,请参阅 HTML 标记对页面的支持For more information, see HTML tag support for pages. 如果其中未列出标记,则可能被忽略。If a tag's not listed there, it'll probably be ignored.

以下列表显示 Microsoft Graph 支持的基本元素类型:The following list shows the basic element types that Microsoft Graph supports:

  • <head><body><head> and <body>

  • <title><meta>,用于设置页面标题和创建日期<title> and <meta> that set the page title and creation date

  • <h1><h6>,用于节标题<h1> through <h6> for section headings

  • <p> 用于段落<p> for paragraphs

  • <ul><ol><li>,用于列表和列表项<ul>, <ol>, and <li> for lists and list items

  • <table><tr><td>,包括嵌套表<table>, <tr> and <td>, including nested tables

  • <pre> 用于预设格式的文本(会保留空格和换行符)<pre> for preformatted text (preserves white space and line breaks)

  • <b><i>,用于粗体和斜体字符样式<b> and <i> for bold and italic character styles

Microsoft Graph 在创建页面时会保留输入 HTML 的语义内容和基本结构,但会转换输入 HTML 以使用一组受支持的 HTML 和 CSS。Microsoft Graph preserves the semantic content and basic structure of the input HTML when it creates pages, but it converts the input HTML to use the supported set of HTML and CSS. OneNote 中不存在的功能没有任何内容可以转换,因此,它们可能无法在源 HTML 中识别。Features that don't exist in OneNote have nothing to be translated to, so they might not be recognized in the source HTML.

示例请求Example request

这个多部分请求示例创建了一个包含图像和嵌入式文件的页面。This example multipart request creates a page that contains images and an embedded file. 必需的演示部分包含定义页面的输入 HTML。The required Presentation part contains the input HTML that defines the page. ImageBlock1 部分包含二进制图像数据,fileBlock1 包含二进制文件数据。The imageBlock1 part contains the binary image data, and fileBlock1 contains the binary file data. 数据部分也可包含 HTML,其中 Microsoft Graph 在 OneNote 页面上将 HTML 呈现为一个图像Data parts can also contain HTML, in which case Microsoft Graph renders the HTML as an image on the OneNote page.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: multipart/form-data; boundary=MyPartBoundary198374

--MyPartBoundary198374
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A page with rendered images and an attached file</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>Here's an image from an <i>online source</i>:</p>
    <img src="https://..." alt="an image on the page" width="500" />
    <p>Here's an image uploaded as <b>binary data</b>:</p>
    <img src="name:imageBlock1" alt="an image on the page" width="300" />
    <p>Here's a file attachment:</p>
    <object data-attachment="FileName.pdf" data="name:fileBlock1" type="application/pdf" />
  </body>
</html>

--MyPartBoundary198374
Content-Disposition:form-data; name="imageBlock1"
Content-Type:image/jpeg

... binary image data ...

--MyPartBoundary198374
Content-Disposition:form-data; name="fileBlock1"
Content-Type:application/pdf

... binary file data ...

--MyPartBoundary198374--

有关介绍如何创建包含图像和其他文件的页面的更多示例,请参阅添加图像和文件、我们的教程示例For more examples that show how to create pages that contain images and other files, see Add images and files, our tutorials, and our samples. 此外,了解如何针对名片捕获、线上食谱和产品列表创建绝对定位元素使用笔记标记提取数据Also, learn how to create absolute positioned elements, use note tags, and extract data for business card captures and online recipe and product listings.

Microsoft Graph 对某些格式非常严格,如多部分邮件正文中的 CRLF 换行符。Microsoft Graph is strict about some formats, such as CRLF newlines in a multipart message body. 为降低创造格式不正确的有效负载的风险,应使用库来构造多部分消息。To reduce the risk of creating malformed payloads, you should use a library to construct multipart messages.

如果收到格式不正确有效负载的 400 状态,请检查换行符和空格的格式,并检查编码问题。If you do receive a 400 status for a malformed payload, check the formatting of newlines and whitespaces, and check for encoding issues. 例如,请尝试使用 charset=utf-8(示例:Content-Type: text/html; charset=utf-8)。For example, try using charset=utf-8 (example: Content-Type: text/html; charset=utf-8).

请参阅输入 HTML 的要求和限制,以及 POST 请求的大小限制See requirements and limitations for input HTML and size limits for POST requests.

POST 页面请求的请求和响应信息Request and response information for POST pages requests

请求数据Request data 说明Description
协议Protocol 所有请求均使用 SSL/TLS HTTPS 协议。All requests use the SSL/TLS HTTPS protocol.
授权标头Authorization header

Bearer {token},其中 {token} 是已注册应用的一个有效 OAuth 2.0 访问令牌。Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

如果缺少或无效,则请求失败,并显示 401 状态代码。If missing or invalid, the request fails with a 401 status code. 请参阅身份验证和权限See Authentication and permissions.

Content-Type 标头Content-Type header

HTML 内容的 text/htmlapplication/xhtml+xml,确定是直接在邮件正文中发送还是在多部分请求的“演示”部分中发送。text/html or application/xhtml+xml for the HTML content, whether it's sent directly in the message body or in the required "Presentation" part of multipart requests.

发送二进制数据时,多部分请求是必需的,并使用 multipart/form-data; boundary=part-boundary 内容类型,其中 {part-boundary} 是一个字符串,表示每个数据部件的开始和结束。Multipart requests are required when sending binary data, and use the multipart/form-data; boundary=part-boundary content type, where {part-boundary} is a string that signals the start and end of each data part.

接受标头Accept header application/json

响应数据Response data 说明Description
成功代码Success code 201 HTTP 状态代码。A 201 HTTP status code.
响应正文Response body 采用 JSON 格式的新页的 OData 表示形式。A OData representation of the new page in JSON format.
错误Errors 如果请求失败,API 将在响应正文的 @api.diagnostics 对象中返回错误。If the request fails, the API returns errors in the @api.diagnostics object in the response body.
位置标头Location header 新页的资源 URL。The resource URL for the new page.
X-CorrelationId 标头X-CorrelationId header 唯一标识该请求的 GUID。A GUID that uniquely identifies the request. 在与 Microsoft 支持部门协作来解决问题时,可以使用此值和日期标头值。You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

构建 Microsoft Graph 服务根 URLConstructing the Microsoft Graph service root URL

Microsoft Graph 服务根 URL 为 Microsoft Graph 的所有调用使用以下格式:The Microsoft Graph service root URL uses the following format for all calls to Microsoft Graph:

https://graph.microsoft.com/{version}/me/onenote/

URL 中的 version 段表示想要使用的 Microsoft Graph 的版本。The version segment in the URL represents the version of Microsoft Graph that you want to use. v1.0 用于稳定的生产代码。Use v1.0 for stable production code. beta 用于试用正在开发的功能。Use beta to try out a feature that's in development. Beta 版中的特性和功能可能会有所更改,因此,不应将其用于生产代码。Features and functionality in beta may change, so you shouldn't use it in your production code.

为当前用户可以访问的 OneNote 内容(拥有和共享)使用 meUse me for OneNote content that the current user can access (owned and shared). 为指定用户已与当前用户共享的 OneNote 内容(此 URL 中)使用 users/{id}Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. 使用 Microsoft Graph 获取用户 ID。Use Microsoft Graph to get user IDs.

OneNote 分区大小限制OneNote section size limitations

对可使用 OneNote API 添加到分区的页面数量有一些限制。There is a limit to the number of pages that you can add to a section using the OneNote API. 当某个分区达到此限制并尝试在该分区中创建新页面时,你将看到 HTTP 状态代码为 507 的响应,并显示消息“已超出每个分区允许的最大页面数”。When this limit is reached for a section and an attempt is made to create a new page in that section, you will see a response with HTTP status code 507 and message "Exceeded the maximum number of pages allowed per section". 有关此错误代码的详细信息,请参阅 OneNote 错误代码For more information about this error code, see OneNote error codes.

可以使用下列解决办法之一:You can use one of the following workarounds:

  • 创建新分区并从中添加新页面。Create a new section and add new pages there.
  • 删除已达到页面限制的现有分区的未使用页面。Delete unused pages of an existing section that has reached the page limit.

权限Permissions

若要创建 OneNote 页面,需要请求相应的权限。To create OneNote pages, you'll need to request appropriate permissions. 选择应用运行所需的最低级别的权限。Choose the lowest level of permissions that your app needs to do its work.

从以下项中进行选择:Choose from:

  • Notes.CreateNotes.Create
  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

有关权限范围及其工作方式的详细信息,请参阅 Microsoft Graph 权限引用For more information about permission scopes and how they work, see Microsoft Graph permissions reference.

另请参阅See also