Обновление содержимого страниц OneNoteUpdate OneNote page content

Относится к: обычные записные книжки в OneDrive | корпоративные записные книжки в Office 365Applies to Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

Чтобы обновить содержимое страницы OneNote, необходимо отправить запрос PATCH в конечную точку content страницы: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 вернет код состояния HTTP 204.Send a JSON change object in the message body. If the request is successful, Microsoft Graph returns a 204 HTTP status code.

Создание URI запросаConstruct 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-id и id используются в качестве идентификаторов 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

HTML-код страницы OneNote содержит текст, изображения и другое содержимое, структурированные с помощью таких элементов, как div, img и ol.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 невозможно использовать веб-ссылки.When updating an image on a OneNote page, you can't use www links. Служба не пытается скачать случайные ресурсы.The service won't try to download random resources. Вместо этого изображение должно быть частью запроса: 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.

Атрибуты объектов JSONAttributes for JSON change objects

Для определения объектов JSON в запросах PATCH используются атрибуты target, action, position и content.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-кода при создании или обновлении страницы.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, необходимый для большинства операций замены.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}" ...>

Не путайте эти идентификаторы со значениями id, определенными во входном HTML-коде.Don't confuse these with any id values defined in the input HTML. Все значения id, отправляемые во входном HTML-коде, отклоняются.All id values sent in the input HTML are discarded.

bodybody Ключевое слово, указывающее на первый разделитель на странице.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.

Применяется только к элементам body, div, ol и ul.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.

Применяется только к элементам body, div, ol и ul.Applies only to body, div, ol, and ul elements.

replacereplace

Заменяет целевой элемент указанным содержимым.Replaces the target with the supplied content.

Для большинства действий replace необходимо использовать сгенерированный идентификатор целевого элемента (кроме элементов img и object внутри разделителя, которые также поддерживают использование 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

Место для добавления предоставленного контента относительно целевого элемента. Если атрибут опущен, по умолчанию он принимает значение after.The location to add the supplied content, relative to the target element. Defaults to after if omitted.

PositionPosition Описание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. Если в содержимом есть двоичные данные, необходимо отправить запрос с использованием типа контента multipart/form-data с частью Commands (см. пример).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).

Сгенерированные идентификаторыGenerated IDs

Microsoft Graph создает значения id для тех элементов на странице, которые можно обновить.Microsoft Graph generates id values for the elements on the page that can be updated. Чтобы получить сгенерированные идентификаторы, используйте выражение строки includeIDs=true в запросе GET:To get generated IDs, use the includeIDs=true query string expression in your GET request:

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

Примечание. API отклоняет все значения id, определенные во входном HTML-коде запросов create-page и update-page.Note: The API discards all id values that are defined in the input HTML of create-page and update-page requests.

Ниже показаны сгенерированные идентификаторы для абзаца и изображения в выходном 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-id или id, как указано ниже.You can specify target elements by using the data-id or id value, as follows:

  • Для действий append и insert в качестве целевого значения можно использовать любой идентификатор.For append and insert actions, you can use either ID as the target value.
  • Для действий replace необходимо использовать сгенерированный идентификатор для всех элементов, кроме заголовка, а также изображений и объектов, находящихся внутри разделителя.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.
    • Чтобы заменить изображения и объекты, находящиеся внутри разделителя, используйте атрибут data-id или id.To 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. Не используйте префикс # со сгенерированным идентификатором.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
(делает целевым первый разделитель на странице)(targets first div on the page)
нетno даyes нетno
divdiv
(абсолютное расположение)(absolute positioned)
нетno даyes нетno
divdiv
(внутри разделителя)(within a div)
даyes
(только идентификатор)(id only)
даyes даyes
img, objectimg, object
(внутри разделителя)(within a div)
даyes нетno даyes
ol, ulol, ul даyes
(только идентификатор)(id only)
даyes даyes
tabletable даyes
(только идентификатор)(id only)
нетno даyes
p, li, h1-h6p, li, h1-h6 даyes
(только идентификатор)(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.

Следующие примеры включают объекты JSON, используемые в запросах PATCH, а также готовые запросы PATCH:The following examples include JSON objects used in PATCH requests and complete PATCH requests:

Добавление дочерних элементовAppend child elements

Действие append добавляет дочерний элемент в элемент body, div (в составе разделителя), ol или ul. Атрибут position определяет, следует ли добавить дочерний элемент перед целевым элементом или после него. Расположение по умолчанию — after.The 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.

Добавление в разделительAppend 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>'
  }
]

Добавление к элементу bodyAppend to the body element

Вы можете использовать сокращение body для добавления дочернего элемента внутри первого разделителя на любой странице.You can use the body shortcut to append a child element inside the first div on any page.

В приведенном ниже примере в первый разделитель на странице добавляется два абзаца: один в качестве первого дочернего элемента, а другой — в качестве последнего.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. По умолчанию задано положение after.The default position is after. См. элементы, поддерживающие действие insert.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 в качестве целевого значения для замены элементов img и object внутри разделителя.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. Для всех остальных элементов, поддерживающих действие replace, необходимо использовать сгенерированный идентификатор.For all other elements that support replace, you must use the generated ID.

Замена изображенияReplace an image

В приведенном ниже примере изображение заменяется разделителем; в качестве целевого элемента используется data-id изображения.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

Этот пример демонстрирует, как обновить таблицу при помощи ее сгенерированного ИД. Замена элементов tr и td не поддерживается, но вы можете заменить таблицу целиком.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

В приведенном ниже примере используется действие replace, чтобы перевести флажок в списке дел в состояние "Выполнено".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.

Примеры выполнения запросов PATCHComplete PATCH request examples

В следующих примерах показаны готовые запросы PATCH.The following examples show complete PATCH requests.

Запрос с текстовым содержимымRequest with text content only

В приведенном ниже примере показан запрос PATCH, в котором используется тип контента application/json.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. Составные запросы включают часть Commands, в которой указывается тип контента application/json и предоставляется массив объектов изменений JSON.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.
Заголовок AuthorizationAuthorization 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-TypeContent-Type header

application/json для массива объектов изменений JSON, отправленного либо непосредственно в тексте сообщения, либо в обязательной части Commands составных запросов.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 Код состояния HTTP 204. Данные JSON не возвращаются по PATCH-запросу.A 204 HTTP status code. No JSON data is returned for a PATCH request.
ОшибкиErrors В статье Коды ошибок для API OneNote в Microsoft Graph описываются ошибки OneNote, которые может возвращать Microsoft Graph.Read Error codes for OneNote APIs in Microsoft Graph to learn about OneNote errors that Microsoft Graph can return.

Составление корневого URL-адреса службы Microsoft GraphConstructing the Microsoft Graph service root URL

Для всех вызовов API OneNote используется следующий формат корневого URL-адреса службы OneNote:The OneNote service root URL uses the following format for all calls to the OneNote API:

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

Сегмент version URL-адреса представляет нужную версию 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. Функции бета-версии могут меняться, поэтому не следует использовать их в производственном коде.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. Использование API Graph для Azure ADUse the Azure AD Graph API.

Примечание. Вы можете получить идентификаторы пользователей, отправив запрос GET к конечной точке https://graph.microsoft.com/v1.0/users.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