Создание страниц OneNoteCreate OneNote pages

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

Чтобы создать страницу OneNote, отправьте запрос POST в конечную точку pages.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 возвращает код состояния HTTP 201.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.

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

Чтобы создать URI запроса POST, начните с корневого URL-адреса службы:To construct the POST request URI, start with the service root URL:

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


Затем добавьте конечную точку pages:Then append the pages endpoint:

  • Создание страницы в любом разделе (по его названию)Create a page in any section (specified by section name)

    .../pages?sectionName=DefaultSection

  • Создание страницы в любом разделе (по его идентификатору)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. Например, если указать название "Мой новый раздел", то оно будет отображаться и дальше, но в последующих запросах можно использовать имя "мой новый раздел".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. Например, пробелы следует кодировать как %20.For 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 создаст новый раздел с указанным вами названием.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-код, определяющий содержимое страницы, называют входным HTML-кодом.The 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-id и data-render-src, описываются в статье Входной и выходной HTML-код.)(Custom attributes, like data-id and data-render-src, are described in Input and output HTML.)

Отправьте входной HTML-код в тексте сообщения запроса POST.Send the input HTML in the message body of the POST request. Вы можете отправить HTML-код прямо в тексте сообщения, используя тип контента application/xhtml+xml или text/html, или в части Presentation составного запроса.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.

Требования и ограничения для входного HTML-кода в запросах POST для страницRequirements and limitations for input HTML in POST pages requests

Отправляя входной HTML-код, учитывайте следующие требования и ограничения:When sending input HTML, be aware of these general requirements and limitations:

  • Входной HTML-код должен быть правильно оформленным XHTML-кодом с кодировкой UTF-8.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. Поддерживаемые атрибуты описываются в статье Входной и выходной HTML-код.For supported attributes, see Input and output HTML.

Поддерживаемые атрибуты HTML и CSS для страниц OneNoteSupported 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. Обязательная часть Presentation содержит входной 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 отображает HTML-код в виде изображения на странице OneNote.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.
Заголовок 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

text/html или application/xhtml+xml для HTML-содержимого, отправляемого либо непосредственно в тексте сообщения, либо в обязательной части Presentation составных запросов.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.

Заголовок AcceptAccept header application/json

Данные ответаResponse data ОписаниеDescription
Код успешного завершенияSuccess code Код состояния HTTP 201A 201 HTTP status code.
Текст ответаResponse body Представление OData новой страницы в формате JSON.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.
Заголовок LocationLocation header URL-адрес ресурса новой страницы.The resource URL for the new page.
Заголовок X-CorrelationIdX-CorrelationId header GUID, уникальный идентификатор запроса.A GUID that uniquely identifies the request. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

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

В корневом URL-адресе службы Microsoft Graph используется следующий формат для всех вызовов 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/

Сегмент version URL-адреса представляет нужную версию 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. Функции бета-версии могут меняться, поэтому не следует использовать их в производственном коде.Features and functionality in beta may change, so you shouldn't use it in your production code.

Используйте значение me для содержимого OneNote, доступного текущему пользователю (если он является владельцем или с ним поделились этим содержимым).Use me for OneNote content that the current user can access (owned and shared). Используйте значение users/{id} для содержимого OneNote, которым указанный (в URL-адресе) пользователь поделился с текущим пользователем.Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Используйте Microsoft Graph для получения идентификаторов пользователей.Use Microsoft Graph to get user IDs.

Разрешения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