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

  • Статья

Область применения: пользовательские записные книжки в OneDrive | корпоративные записные книжки в Microsoft 365

Чтобы обновить содержимое страницы OneNote, необходимо отправить запрос PATCH в конечную точку content страницы:

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

Отправьте объект изменений JSON в тексте сообщения. В случае успешного выполнения запроса Microsoft Graph возвращает код состояния HTTP 204.

Создание URI запроса

Чтобы создать URI запроса, начните с корневого URL-адреса службы:

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


Затем добавьте конечную точку content страницы:

  • Получение HTML-кода страницы и всех определенных значений data-id

    ../pages/{id}/content

  • Получение HTML-кода страницы, всех определенных значений data-id и всех созданных значений id

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

Значения data-id и id используются в качестве идентификаторов target для элементов, которые требуется изменить.

Полный URI запроса будет выглядеть так:

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

Узнайте больше о корневом URL-адресе службы.

Составление текста сообщения

HTML-код страницы OneNote содержит текст, изображения и другое содержимое, структурированные с помощью таких элементов, как div, img и ol. Для обновления содержимого страницы OneNote необходимо добавлять и заменять элементы HTML на странице.

Изменения отправляются в тексте сообщения в виде массива объектов JSON. В каждом объекте указываются целевой элемент, новое содержимое HTML и действия, которые нужно выполнить с содержимым.

Следующий массив определяет два изменения. Первое вставляет изображение над абзацем в качестве элемента того же уровня, а второе добавляет элемент в список в качестве последнего дочернего элемента.

Примечание.

При обновлении изображения на странице OneNote нельзя использовать www-ссылки. Служба не будет пытаться скачать случайные ресурсы. Вместо этого изображение должно быть частью запроса либо по url-адресу image-data-url, либо по имени-части многокомпонентного запроса.

[
   {
    '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>'
  }
]

См. другие примеры.

Атрибуты объектов JSON

Для определения объектов JSON в запросах PATCH используются атрибуты target, action, position и content.

target

Обновляемый элемент. Значением должен быть один из следующих идентификаторов:

Идентификатор Описание
#{data-id}

Этот идентификатор при желании определяется для элементов входного HTML-кода при создании или обновлении страницы. Добавьте перед этим значением префикс #.

Пример:
'target':'#intro' задает в качестве целевого элемент <div data-id="intro" ...>
id

Это сгенерированный идентификатор из Microsoft Graph, необходимый для большинства операций замены. Не добавляйте перед ним префикс #.

Пример:
'target':'div:{33f8a2...}{37}' задает в качестве целевого элемент <div id="div:{33f8a2...}{37}" ...>

Не путайте эти идентификаторы со значениями id, определенными во входном HTML-коде. Все значения id, отправляемые во входном HTML-коде, отклоняются.
body Ключевое слово, указывающее на первый разделитель на странице. Не добавляйте перед ним префикс #.
title Ключевое слово, указывающее на заголовок страницы. Не добавляйте перед ним префикс #.

action

Действие, выполняемого с целевым элементом. См. раздел Поддерживаемые действия для элементов.

Действие Описание
append

Добавляет указанное содержимое к целевому элементу в качестве первого или последнего дочернего элемента, в зависимости от значения атрибута position.

Применяется только к элементам body, div, ol и ul.
insert Добавляет указанное содержимое в качестве элемента того же уровня перед целевым элементом или после него, в зависимости от значения атрибута position.
prepend

Добавляет указанное содержимое к целевому элементу в качестве первого дочернего элемента. Сокращение от действия append + before.

Применяется только к элементам body, div, ol и ul.
replace

Заменяет целевой элемент указанным содержимым.

Для большинства действий replace необходимо использовать сгенерированный идентификатор целевого элемента (кроме элементов img и object внутри разделителя, которые также поддерживают использование data-id).

position

Место для добавления предоставленного контента относительно целевого элемента. Если атрибут опущен, по умолчанию он принимает значение after.

Position Описание
after (по умолчанию)

С действием append: последний дочерний элемент целевого элемента.

С действием insert: следующий элемент того же уровня, что и целевой элемент.
before

С действием append: первый дочерний элемент целевого элемента.

С действием insert: предыдущий элемент того же уровня, что и целевой элемент.

content

Строка правильно оформленного HTML-кода, который нужно добавить на страницу, а также двоичные данные изображения или файла. Если в содержимом есть двоичные данные, необходимо отправить запрос с использованием типа контента multipart/form-data с частью Commands (см. пример).

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

Microsoft Graph создает значения id для тех элементов на странице, которые можно обновить. Чтобы получить сгенерированные идентификаторы, используйте выражение строки includeIDs=true в запросе GET:

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

Примечание.

API отбрасывает все значения идентификаторов , определенные во входном HTML-коде запросов на создание страницы и обновление.

Ниже показаны сгенерированные идентификаторы для абзаца и изображения в выходном HTML-коде страницы.

<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-запроса.

Вы можете указать целевые элементы, используя значение data-id или id, как указано ниже.

  • Для действий append и insert в качестве целевого значения можно использовать любой идентификатор.
  • Для действий replace необходимо использовать сгенерированный идентификатор для всех элементов, кроме заголовка, а также изображений и объектов, находящихся внутри разделителя.
    • Чтобы заменить заголовок, используйте ключевое слово title.
    • Чтобы заменить изображения и объекты, находящиеся внутри разделителя, используйте атрибут data-id или id.

В приведенном ниже примере используется значение id целевого элемента. Не используйте префикс # со сгенерированным идентификатором.

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

Поддерживаемые элементы и действия

Многие элементы на странице можно обновлять, но каждый тип элемента поддерживает определенные действия. Ниже показаны поддерживаемые целевые элементы и поддерживаемые ими действия по обновлению.

Элемент Заменить Добавление дочернего элемента Вставка элемента того же уровня
body
(делает целевым первый разделитель на странице)		 нет да нет
div
(абсолютное расположение)		 нет да нет
div
(внутри разделителя)		 да
(только идентификатор)		 да да
img, object
(внутри разделителя)		 да нет да
ol, ul да
(только идентификатор)		 да да
table да
(только идентификатор)		 нет да
p, li, h1-h6 да
(только идентификатор)		 нет да
title да нет Нет

Указанные ниже элементы не поддерживают никаких действий обновления.

Примеры запросов

Запрос на обновление содержит одно или несколько изменений, представленных в виде объектов JSON. Эти объекты могут определять различные целевые элементы на странице, а также различные действия и содержимое для целевых элементов.

Следующие примеры включают объекты JSON, используемые в запросах PATCH, а также готовые запросы PATCH:

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

Действие append добавляет дочерний элемент в элемент body, div (в составе разделителя), ol или ul. Атрибут position определяет, следует ли добавить дочерний элемент перед целевым элементом или после него. По умолчанию задано положение after.

Добавление в разделитель

В приведенном ниже примере в элемент div1 добавляется два дочерних узла. Изображение добавляется в качестве первого дочернего элемента, а абзац — в качестве последнего.

[
 {
    '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

Вы можете использовать сокращение body для добавления дочернего элемента внутри первого разделителя на любой странице.

В приведенном ниже примере в первый разделитель на странице добавляется два абзаца: один в качестве первого дочернего элемента, а другой — в качестве последнего. Не используйте префикс # с целевым элементом body. В этом примере действие prepend используется в качестве сокращения от действия 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>'
  }
]

Добавление в список

В следующем примере элемент списка добавляется в качестве последнего дочернего элемента к целевому списку. Свойство list-style-type определено, так как элемент использует стиль списка не по умолчанию.

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

Вставка элементов того же уровня

Действие insert добавляет элемент того же уровня в целевой элемент. Атрибут position определяет, где следует вставлять элемент: до или после целевого элемента. По умолчанию задано положение after. См. элементы, поддерживающие действие insert.

Вставка элементов того же уровня

В следующем примере два узла того же уровня добавляются на страницу. Над элементом para1 добавляется изображение, а под элементом para2 — абзац.

[
  {
     '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>'
  }
]

Замена элементов

Вы можете использовать data-id или сгенерированный id в качестве целевого значения для замены элементов img и object внутри разделителя. Чтобы заменить заголовок, используйте ключевое слово title. Для всех остальных элементов, поддерживающих действие replace, необходимо использовать сгенерированный идентификатор.

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

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

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

Обновление таблицы

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

[
  {
    '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>'
  }
]

Изменение заголовка

В этом примере показано, как изменить заголовок страницы. Чтобы изменить заголовок, используйте ключевое слово title в качестве целевого значения. Не используйте префикс # в целевом заголовке.

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

Обновление элемента списка дел

В приведенном ниже примере используется действие replace, чтобы перевести флажок в списке дел в состояние "Выполнено".

[
  {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'replace',
    'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
  }
]

Дополнительные сведения об использовании атрибута data-tag см. в этой статье.

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

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

Запрос с текстовым содержимым

В приведенном ниже примере показан запрос PATCH, в котором используется тип контента application/json. Этот формат можно использовать, если контент не содержит двоичных данных.

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>'
  }
]

Составной запрос с двоичным содержимым

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

Данные запроса Описание
Протокол Все запросы используют протокол SSL/TLS для HTTPS.
Заголовок Authorization

Bearer {token}, где {token} — действительный маркер доступа OAuth 2.0 для зарегистрированного приложения.

Если он отсутствует или является недействительным, запрос завершится ошибкой с кодом состояния 401. См. статью Проверка подлинности и разрешения.
Заголовок Content-Type

application/json для массива объектов изменений JSON, отправленного либо непосредственно в тексте сообщения, либо в обязательной части Commands составных запросов.

Составные запросы необходимы при отправке двоичных данных и используют тип контента multipart/form-data; boundary=part-boundary, где {part-boundary} — это строка, обозначающая начало и конец каждой части данных.

Данные в ответе Описание
Код успешного завершения Код состояния HTTP 204. Данные JSON не возвращаются по PATCH-запросу.
Ошибки В статье Коды ошибок для API OneNote в Microsoft Graph описываются ошибки OneNote, которые может возвращать Microsoft Graph.

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

Для всех вызовов API OneNote используется следующий формат корневого URL-адреса службы OneNote:

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

Сегмент version URL-адреса представляет нужную версию Microsoft Graph. Значение v1.0 предназначено для стабильного производственного кода. Используйте значение beta, чтобы опробовать функцию, находящуюся на стадии разработки. Функции бета-версии могут меняться, поэтому не следует использовать их в производственном коде.

Значение me предназначено для содержимого OneNote, доступного текущему пользователю (если он является владельцем или с ним поделились этим содержимым). Значение users/{id} предназначено для содержимого OneNote, которым указанный (в URL-адресе) пользователь поделился с текущим пользователем. Используйте API для работы с пользователями.

Примечание.

Вы можете получить идентификаторы пользователей, выполнив запрос GET на https://graph.microsoft.com/v1.0/users.

Разрешения

Для обновления страниц OneNote необходимо запрашивать соответствующие разрешения. Выберите минимальный уровень разрешений, необходимый для работы вашего приложения.

  • Notes.ReadWrite
  • Notes.ReadWrite.All

Дополнительные сведения об областях разрешений и принципе их работы см. в разделе Области разрешений OneNote.

Связанные материалы