更新 OneNote 页面内容Update OneNote page content

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

若要更新 OneNote 页面的内容,请向此页面的 content 终结点发送 PATCH 请求:To update the content of a OneNote page, you send a PATCH request to the page's content endpoint:

PATCH ../notes/pages/{id}/content

在邮件正文中发送 JSON 更改对象。如果请求成功,Microsoft Graph 便会返回 204 HTTP 状态代码。Send a JSON change object in the message body. If the request is successful, Microsoft Graph returns a 204 HTTP status code.

构建请求 URIConstruct the request URI

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

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


然后,追加页面的 content 终结点:Then append the page's content endpoint:

  • 获取页面 HTML 和所有定义的 data-idGet the page HTML and all defined data-id values

    ../pages/{id}/content

  • 获取页面 HTML、所有定义的 data-id 值和所有生成的 idGet the page HTML, all defined data-id values, and all generated id values

    ../pages/{page-id}/content?includeIDs=true

data-idid 值均用作要更新的元素的 target 标识符。The data-id and id values are used as target identifiers for the elements you want to update.

完整的请求 URI 将如下所示:Your full request URI will look like this:

https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content

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

构造邮件正文Construct the message body

OneNote 页面的 HTML 包含文本、图像和组织到结构中的其他内容,如 divimgol 元素。The HTML of a OneNote page contains text, images, and other content organized into structures such as div, img, and ol elements. 若要更新 OneNote 页面内容,请添加并替换页面上的 HTML 元素。To update OneNote page content, you add and replace HTML elements on the page.

所做的更改将以 JSON 更改对象数组的形式在邮件正文中发送。Your changes are sent in the message body as an array of JSON change objects. 每个对象指定目标元素、新 HTML 内容以及使用内容可完成的操作。Each object specifies the target element, new HTML content, and what to do with the content.

以下数组定义了两个更改。第一个更改在段落上方插入一张图像作为同级对象,第二个更改向列表中附加一个项目作为最后一个子元素。The following array defines two changes. The first inserts an image above a paragraph as a sibling, and the second appends an item to a list as a last child.

备注

在 OneNote 页面上更新图像时,你无法使用 www 链接。When updating an image on a OneNote page, you can't use www links. 该服务不会尝试下载随机资源。The service won't try to download random resources. 相反,图像必须是请求的一部分,无论是通过 image-data-url 还是多部分请求的部件名称。Instead, the image must be part of the request, either by an image-data-url or a part-name of a multipart request.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url-or-part-name" alt="Image above the target paragraph" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the end of the list</li>'
  }
]

请参阅更多示例See more examples.

JSON 更改对象的属性Attributes for JSON change objects

使用 targetactionpositioncontent 属性来定义用于 PATCH 请求的 JSON 对象。Use the target, action, position, and content attributes to define JSON objects for PATCH requests.

targettarget

要更新的元素。值必须是下列标识符之一:The element to update. The value must be one of the following identifiers:

标示符Identifier 说明Description
#{data-id}#{data-id}

创建页面更新页面时,可以选择在输入 HTML 中的元素上定义此 ID。This ID is optionally defined on elements in the input HTML when creating a page or updating a page. 将 # 用作此值的前缀。Prefix the value with a #.

示例:Example:
'target':'#intro' 定位元素 <div data-id="intro" ...>'target':'#intro' targets the element <div data-id="intro" ...>

idid

这是从 Microsoft Graph 生成的 ID,对大多数替换操作所都是必需的值。This is the generated ID from Microsoft Graph, and is required for most replace operations. 不要使用 # 作为前缀。Do not prefix with a #.

示例:Example:
'target':'div:{33f8a2...}{37}' 定位元素 <div id="div:{33f8a2...}{37}" ...>'target':'div:{33f8a2...}{37}' targets the element <div id="div:{33f8a2...}{37}" ...>

不要将其与 输入 HTML 中定义的任何 id 值混淆。Don't confuse these with any id values defined in the input HTML. 所有在输入 HTML 中发送的 id 值都将被丢弃。All id values sent in the input HTML are discarded.

bodybody 针对页面上第一个 div 的关键字。The keyword that targets the first div on the page. 不要使用 # 作为前缀。Do not prefix with a #.
titletitle 针对页标题的关键字。The keyword that targets the page title. 不要使用 # 作为前缀。Do not prefix with a #.

actionaction

要在目标元素上执行的操作。请参阅元素的支持操作The action to perform on the target element. See supported actions for elements.

操作Action 说明Description
appendappend

将提供的内容作为第一个或最后一个子元素添加到由 position 属性所确定的目标。Adds the supplied content to the target as a first or last child, as determined by the position attribute.

仅适用于 bodydivolul 元素。Applies only to body, div, ol, and ul elements.

insertinsert 将提供的内容作为同级元素添加到由 position 属性确定的目标之前或之后。Adds the supplied content as a sibling before or after the target, as determined by the position attribute.
prependprepend

将提供的内容作为第一个子元素添加到目标。Adds the supplied content to the target as a first child. append + before 的快捷方式。Shortcut for append + before.

仅适用于 bodydivolul 元素。Applies only to body, div, ol, and ul elements.

replacereplace

使用提供的内容替换目标。Replaces the target with the supplied content.

大多数 替换 操作需要为目标使用 生成的 ID(除 div 中的 imgobject 元素之外,还支持使用 data-id)。Most replace actions require using the generated ID for the target (except img and object elements within a div, which also support using data-id).

positionposition

要添加所提供的内容的位置,与目标元素有关。如果省略,默认值为 afterThe location to add the supplied content, relative to the target element. Defaults to after if omitted.

位置Position 说明Description
after(默认)after (default)

使用 append:目标元素的最后一个子元素。With append: The last child of the target element.

使用 insert:目标元素的后续同级元素。With insert: The subsequent sibling of the target element.

beforebefore

使用 append:目标元素的第一个子元素。With append: The first child of the target element.

使用 insert:目标元素的前导同级元素。With insert: The preceding sibling of the target element.

contentcontent

要添加到页面的格式标准的 HTML 字符串或任意图像或二进制文件数据。A string of well-formed HTML to add to the page, and any image or file binary data. 如果内容包含二进制数据,则必须使用包含“Commands”部件的 multipart/form-data 内容类型发送请求(请参阅示例)。If the content contains binary data, the request must be sent using the multipart/form-data content type with a "Commands" part (see an example).

生成的 IDGenerated IDs

Microsoft Graph 将为可更新页面上的元素生成 id 值。Microsoft Graph generates id values for the elements on the page that can be updated. 若要获取生成的 ID,请在 GET 请求中使用 includeIDs=true 查询字符串表达式:To get generated IDs, use the includeIDs=true query string expression in your GET request:

GET ../notes/pages/{page-id}/content?includeIDs=true

注意: API 会放弃在创建页面和更新页面请求的 输入 HTML 中定义的所有 id 值。Note: The API discards all id values that are defined in the input HTML of create-page and update-page requests.

以下示例显示了段落的生成 ID,以及页面的输出 HTML 中的图像。The following example shows generated IDs for a paragraph and an image in the output HTML of a page.

<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />

页面更新后,生成的 id 值可能会更改,因此您应该在构建使用当前值的 PATCH 请求之前获取当前值。Generated id values might change after a page update, so you should get the current values before building a PATCH request that uses them.

可以使用 data-idid 值指定目标元素,如下所示:You can specify target elements by using the data-id or id value, as follows:

  • 对于 appendinsert 操作,可以使用任一 ID 作为目标值。For append and insert actions, you can use either ID as the target value.
  • 对于 replace 操作,必须为除页标题及 div 中的图像和对象之外的所有元素使用生成的 ID。For replace actions, you must use the generated ID for all elements except for the page title and images and objects that are within a div.
    • 若要替换标题,请使用 title 关键字。To replace a title, use the title keyword.
    • 若要替换 div 中的图像和对象,请使用 data-ididTo replace images and objects that are within a div, use either data-id or id.

以下示例为目标使用了 id 值。The following example uses the id value for the target. 不要将 # 前缀用于生成的 ID。Don't use the # prefix with a generated ID.

[
   {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'insert',
    'position':'before',
    'content':'<p>This paragraph goes above the target paragraph.</p>'
  }
]

受支持的元素和操作Supported elements and actions

可以更新页面上的许多元素,但每个元素类型支持特定操作。Many elements on the page can be updated, but each element type supports specific actions. 下表显示了支持的目标元素和它们支持的更新操作。The following table shows supported target elements and the update actions that they support.

元素Element 替换Replace 附加子元素Append child 插入同级元素Insert sibling
bodybody
(目标为页面上的第一个 div)(targets first div on the page)
no yes no
divdiv
绝对定位(absolute positioned)
no yes no
divdiv
(在 div 中)(within a div)
yes
(仅 ID)(id only)
yes yes
img, objectimg, object
(在 div 中)(within a div)
yes no yes
ol, ulol, ul yes
(仅 ID)(id only)
yes yes
tabletable yes
(仅 ID)(id only)
no yes
p, li, h1-h6p, li, h1-h6 yes
(仅 ID)(id only)
no yes
titletitle yes no no

以下元素不支持任何更新操作。The following elements do not support any update actions.

示例请求Example requests

更新请求包含表示为 JSON 更改对象的一个或多个更改。An update request contains one or more changes represented as JSON change objects. 这些对象可以定义页面上的不同目标,以及定义目标的不同操作和内容。These objects can define different targets on the page and different actions and content for the targets.

以下示例包括 PATCH 请求中使用的 JSON 对象和完整的 PATCH 请求:The following examples include JSON objects used in PATCH requests and complete PATCH requests:

追加子元素Append child elements

append 操作向 bodydiv(分区内)、olul 元素添加一个子元素。position 属性确定是在目标之前还是之后附加子元素。默认位置为 afterThe append action adds a child to a body, div (within a div), ol, or ul element. The position attribute determines whether to append the child before or after the target. The default position is after.

追加到 divAppend to a div

以下示例将两个子节点添加到 div1 元素。The following example adds two child nodes to the div1 element. 它添加图像作为第一个子元素,添加段落作为最后一个子元素。It adds an image as the first child and a paragraph as the last child.

[
 {
    'target':'#div1',
    'action':'append',
    'position':'before',
    'content':'<img data-id="first-child" src="image-url-or-part-name" />'
  },
  {
    'target':'#div1',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph appended to the div</p>'
  }
]

追加到 body 元素Append to the body element

可以使用 body 快捷方式来追加任何页面上的第一个 div 内的子元素。You can use the body shortcut to append a child element inside the first div on any page.

以下示例将两个段落作为第一个子元素和最后一个子元素添加到页面上第一个 div。The following example adds two paragraphs as the first child and the last child to the first div on the page. 不要将 # 用于 body 目标。Don't use a # with the body target. 此示例使用 prepend 操作作为 append + before 的快捷方式。This example uses the prepend action as a shortcut for append + before.

[
  {
    'target':'body',
    'action':'prepend',
    'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
  },
  {
    'target':'body',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
  }
]

追加到列表Append to a list

以下示例将一个列表项目作为最后一个子元素添加到目标列表。因为项目使用非默认的列表演示,因此应定义 list-style-type 属性。The following example adds a list item as a last child to the target list. The list-style-type property is defined because the item uses a non-default list style.

[
  {
    'target':'#circle-ul',
    'action':'append',
    'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
  }
]

插入同级元素Insert sibling elements

insert 操作将同级元素添加到目标元素。The insert action adds a sibling to the target element. position 属性确定要将同级元素插入到目标之前还是之后。The position attribute determines whether to insert the sibling before or after the target. 默认位置是 afterThe default position is after. 请参阅 支持 插入 的元素See elements that support insert.

插入同级Insert siblings

以下示例向页面添加两个同级节点。它在 para1 元素上方添加一个图像,在 para2 元素下方添加一个段落。The following example adds two sibling nodes to the page. It adds an image above the para1 element and a paragraph below the para2 element.

[
  {
     'target':'#para1',
     'action':'insert',
     'position':'before',
     'content':'<img src="image-data-url-or-part-name" alt="Image inserted above the target" />'
  },
  {
    'target':'#para2',
     'action':'insert',
     'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
  }
]

替换元素Replace elements

可以使用 data-id 或生成的 id 作为目标值来替换 div 中的 imgobject 元素。You can use either the data-id or generated id as the target value to replace img and object elements that are within a div. 若要替换页标题,请使用 title 关键字。To replace the page title, use the title keyword. 对于所有其他 支持 替换的元素,必须使用生成的 ID。For all other elements that support replace, you must use the generated ID.

替换图像Replace an image

以下示例使用图像的 data-id 作为目标来替换 div 中的图像。The following example replaces an image with a div by using the image's data-id as the target.

[
  {
    'target':'#img1',
    'action':'replace',
    'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
  }
]

更新表格Update a table

此示例显示如何使用生成的 ID 更新表格。不支持替换 trtd 元素,但您可以替换整个表格。This example shows how to update a table by using its generated ID. Replacing tr and td elements is not supported, but you can replace the entire table.

[
  {
    'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
    'action':'replace',
    'content':'<table data-id="football">
      <tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
      <tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
      <tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
      <tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
  }
]

更改标题Change the title

此示例说明如何更改页面的标题。This example shows how to change the title of a page. 若要更改标题,请使用 title 关键字作为目标值。To change the title, use the title keyword as the target value. 不要将 # 用于标题目标。Don't use a # with the title target.

[
  {
    'target':'title',
    'action':'replace',
    'content':'New title'
  }
]

更新待办事项Update a to-do item

以下示例使用替换操作将待办事项复选框项更改为完成状态。The following example uses the replace action to change a to-do check box item to a completed state.

[
  {
    'target':'#task1',
    'action':'replace',
    'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
  }
]

有关使用 data-tag 属性的详细信息,请参阅 使用注释标记See Use note tags for more about using the data-tag attribute.

完整的 PATCH 请求示例Complete PATCH request examples

以下示例显示了完整的 PATCH 请求。The following examples show complete PATCH requests.

仅包含文本内容的请求Request with text content only

以下示例显示使用 application/json 内容类型的 PATCH 请求。The following example shows a PATCH request that uses the application/json content type. 内容不包含二进制数据时,可使用此格式。You can use this format when your content doesn't contain binary data.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url" alt="New image from a URL" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

包含二进制内容的多部分请求Multipart request with binary content

以下示例显示包含二进制数据的多部分 PATCH 请求。The following example shows a multipart PATCH request that includes binary data. 多部分请求需要指定 application/json 内容类型并包含 JSON 更改对象数组的“Commands”部件。Multipart requests require a "Commands" part that specifies the application/json content type and contains the array of JSON change objects. 其他数据部件可包含二进制数据。Other data parts can contain binary data. 部件名称通常是附加有毫秒为单位或随机 GUID 当前时间的字符串。Part names typically are strings appended with the current time in milliseconds or a random GUID.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}

--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json

[
  {
    'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
    'action':'replace',
    'content':'<img src="name:image-part-name" alt="New binary image" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png

... binary image data ...

--PartBoundary123--

PATCH 请求的请求和响应信息Request and response information for PATCH 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

JSON 更改对象的数组的 application/json,确定是直接在邮件正文中发送还是在必须的多部分请求的“命令”部分中发送。application/json for the array of JSON change objects, whether sent directly in the message body or in the required "Commands" 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.


响应数据Response data 说明Description
成功代码Success code 204 HTTP 状态代码。PATCH 请求未返回任何 JSON 数据。A 204 HTTP status code. No JSON data is returned for a PATCH request.
错误Errors 请阅读 Microsoft Graph 中 OneNote API 的错误代码,以了解 Microsoft Graph 可以返回的 OneNote 错误。Read Error codes for OneNote APIs in Microsoft Graph to learn about OneNote errors that Microsoft Graph can return.

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

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

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 用于稳定的生产代码。v1.0 is for stable production code. beta 用于试用正在开发的功能。beta is 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.

me 用于为当前用户可以访问的 OneNote 内容(拥有和共享)。me is for OneNote content that the current user can access (owned and shared). users/{id} 用于指定用户已与当前用户共享的 OneNote 内容(此 URL 中)。users/{id} is for OneNote content that the specified user (in the URL) has shared with the current user. 使用 Azure AD 图形 APIUse the Azure AD Graph API.

注意: 可以通过在 https://graph.microsoft.com/v1.0/users 上发出 GET 请求来获取用户 ID。Note: You can get user ids by making a GET request on https://graph.microsoft.com/v1.0/users.

权限Permissions

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

  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

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

另请参阅See also