Поделиться через

Получение содержимого и структуры OneNote

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

Чтобы получить содержимое и структуру OneNote с помощью API OneNote Microsoft Graph, необходимо отправить запрос GET к целевой конечной точке. Например:

GET ../onenote/pages/{id}

Если запрос выполнен успешно, Microsoft Graph возвращает код состояния HTTP 200 OK и запрашиваемые объекты или содержимое. Объекты OneNote возвращаются в виде объектов JSON, соответствующих спецификации OData версии 4.0.

С помощью параметров строки запроса вы можете фильтровать запросы и повышать производительность.

Примечание.

Если вы создаете решение, которое поддерживает один из следующих сценариев, вы столкнетесь с ограничениями API OneNote:

  • Резервное копирование и восстановление разделов OneNote
  • Резервное копирование и восстановление записных книжек OneNote

Для операций резервного копирования и восстановления см. статью Рекомендации по обнаружению файлов и определению изменений в масштабе.

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

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

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

Затем добавьте конечную точку нужного ресурса. (Пути к ресурсам показаны в следующем разделе.)

Полный URI запроса будет выглядеть так, как в одном из следующих примеров:

  • https://graph.microsoft.com/v1.0/me/onenote/notebooks/{id}/sections
  • https://graph.microsoft.com/v1.0/me/onenote/notes/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?select=title,self

Примечание.

См. дополнительные сведения о корневом URL-адресе службы.

Пути к ресурсам для запросов GET

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

Коллекция Page

Получение страниц (метаданных) из всех записных книжек.

../pages[?filter,orderby,select,expand,top,skip,count]

Получение страниц (метаданных) из определенного раздела.

../sections/{section-id}/pages[?filter,orderby,select,expand,top,skip,count,pagelevel]

По умолчанию для страниц используется порядок сортировки lastModifiedTime desc.

Запрос по умолчанию разворачивает родительский раздел и выбирает свойства id, name и self этого раздела.

По умолчанию в ответ на запросы GET для страниц возвращаются только первые 20 записей. В ответах на запросы, в которых не указан параметр top, возвращается ссылка @odata.nextLink, с помощью которой можно получить следующие 20 записей.

Для коллекции страниц в разделе используйте параметр pagelevel, чтобы возвращать уровень отступа страниц и их порядок в разделе.

Пример

GET ../sections/{section-id}/pages?pagelevel=true

Объект Page

Получение метаданных определенной страницы.

../pages/{page-id}[?select,expand,pagelevel]

Запросы страниц могут разворачивать свойства parentNotebook и parentSection.

Запрос по умолчанию разворачивает родительский раздел и выбирает свойства id, name и self этого раздела.

С помощью параметра pagelevel можно вернуть уровень отступа страницы и ее порядковый номер в родительском разделе.

Пример

GET ../pages/{page-id}?pagelevel=true

Предварительный просмотр страницы

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

../pages/{page-id}/preview

Отклик JSON содержит часть контента для предварительного просмотра, благодаря которому пользователи могут узнать, что находится на странице.

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.PagePreview",
  "previewText":"text-snippet"
}

Свойство previewText содержит фрагмент текста со страницы. Microsoft Graph возвращает полные фразы длиной до 300 символов.

HTML-контент страницы

Получение HTML-контента страницы.

../pages/{page-id}/content[?includeIDs]

(Дополнительные сведения о возвращаемом HTML-контенте.)

Указав в строке запроса параметр includeIDs=true, можно получить созданные идентификаторы, используемые для обновления страницы.

Коллекция Section

Получение всех разделов всех записных книжек, принадлежащих пользователю, включая разделы из вложенных групп разделов.

../sections[?filter,orderby,select,top,skip,expand,count]

Получение всех разделов, вложенных непосредственно в определенную группу разделов.

../sectionGroups/{sectiongroup-id}/sections[?filter,orderby,select,top,skip,expand,count]

Получение всех разделов, вложенных непосредственно в определенную записную книжку.

../notebooks/{notebook-id}/sections[?filter,orderby,select,top,skip,expand,count]

Запросы разделов могут разворачивать свойства parentNotebook и parentSectionGroup.

По умолчанию для разделов используется порядок сортировки name asc.

Запрос по умолчанию разворачивает родительскую записную книжку и родительскую группу разделов и выбирает их свойства id, name и self.

Объект Section

Получение определенного раздела.

../sections/{section-id}[?select,expand]

Запросы разделов могут разворачивать свойства parentNotebook и parentSectionGroup.

Запрос по умолчанию разворачивает родительскую записную книжку и родительскую группу разделов и выбирает их свойства id, name и self.

Коллекция SectionGroup

Получение всех групп разделов из всех записных книжек, принадлежащих пользователю, включая вложенные.

../sectionGroups[?filter,orderby,select,top,skip,expand,count]

Получение всех групп разделов, вложенных непосредственно в определенную записную книжку.

../notebooks/{notebook-id}/sectionGroups[?filter,orderby,select,top,skip,expand,count]

Запросы групп разделов могут разворачивать свойства sections, sectionGroups, parentNotebook и parentSectionGroup.

По умолчанию для групп разделов используется порядок сортировки name asc.

Запрос по умолчанию разворачивает родительскую записную книжку и родительскую группу разделов и выбирает их свойства id, name и self.

Объект SectionGroup

Получение определенной группы разделов.

../sectionGroups/{sectiongroup-id}[?select,expand]

Запросы групп разделов могут разворачивать свойства sections, sectionGroups, parentNotebook и parentSectionGroup.

Запрос по умолчанию разворачивает родительскую записную книжку и родительскую группу разделов и выбирает их свойства id, name и self.

Коллекция Notebook

Получение всех записных книжек, принадлежащих пользователю.

../notebooks[?filter,orderby,select,top,skip,expand,count]

Запросы записных книжек могут разворачивать свойства sections и sectionGroups.

По умолчанию для записных книжек используется порядок сортировки name asc.

Объект Notebook

Получение определенной записной книжки.

../notebooks/{notebook-id}[?select,expand]

Запросы записных книжек могут разворачивать свойства sections и sectionGroups.

Ресурс изображений или других файлов

Получение двоичных данных определенного ресурса.

../resources/{resource-id}/$value

URI ресурса файла можно найти в выходном HTML-коде страницы.

Например, тег img содержит конечные точки для исходного изображения в атрибуте data-fullres-src и оптимизированное изображение в атрибуте src.

Пример

<img 
    src="https://www.onenote.com/api/v1.0/me/notes/resources/{image-id}/$value"  
    data-src-type="image/png"
    data-fullres-src="https://www.onenote.com/api/v1.0/resources/{image-id}/$value"  
    data-fullres-src-type="image/png" ... />

Тег object содержит конечную точку файлового ресурса в атрибуте data.

Пример

<object
    data="https://www.onenote.com/api/v1.0/me/notes/resources/{file-id}/$value"
    data-attachment="fileName.pdf" 
    type="application/pdf" ... />

Примечание.

Получение коллекции ресурсов не поддерживается.

При получении файлового ресурса не требуется включать в запрос тип контента Accept.

Дополнительные сведения о запросах GET см. в следующих статьях документации по API REST Microsoft Graph:

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

Вы можете запросить сущности OneNote, чтобы получить только необходимые сведения. Ниже показаны некоторые способы использования поддерживаемых параметров строки в запросах GET к Microsoft Graph.

Помните:

  • Все запросы GET начинаются с корневого URL-адреса службы.

    Примеры: https://www.onenote.com/api/v1.0/me/notes и https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/.

  • Пробелы в строке запроса URL следует кодировать как %20.

    Пример: filter=title%20eq%20'biology'.

  • В случае имен свойств и сравнения строк OData учитывается регистр. Рекомендуем использовать функцию OData tolower для сравнения строк.

    Пример: filter=tolower(name) eq 'spring'.

filter

Получение всех страниц, созданных определенным приложением.

[GET] ../pages?filter=createdByAppId eq 'WLID-000000004C12821A'

select

Получите заголовок, клиентские ссылки OneNote и ссылку contentUrl для всех страниц.

[GET] ../pages?select=title,links,contentUrl

expand

Получение всех записных книжек, а также разворачивание их разделов и групп разделов.

[GET] ../notebooks?expand=sections,sectionGroups

Получение определенной группы разделов и разворачивание ее разделов и групп разделов.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections,sectionGroups

Получение страницы и разворачивание ее родительского раздела и родительской записной книжки.

[GET] ../pages/{page-id}?expand=parentSection,parentNotebook

expand (несколько уровней)

Получение всех записных книжек и разворачивание их разделов и групп разделов, а также разворачивание всех разделов в каждой группе разделов.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections)

Примечание.

Развертывание родительских элементов (у которых есть дочерние элементы) и развертывание дочерних элементов (у которых есть родительские элементы) приводит к созданию циклической ссылки. Такой порядок действий не поддерживается.

expand и select (несколько уровней)

Получение имени и ссылки self для определенной группы разделов, а также получение имени и ссылок self для всех ее разделов.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections(select=name,self)&select=name,self

Получение имени и ссылки self для всех разделов, а также получение имени и времени создания родительской записной книжки каждого раздела.

[GET] ../sections?expand=parentNotebook(select=name,createdTime)&select=name,self

Получение названий и идентификаторов всех страниц, а также получение названия родительского раздела и родительской записной книжки. 
[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)

expand и levels (несколько уровней)

Получение всех записных книжек, разделов и групп разделов.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections,sectionGroups(levels=max;expand=sections))

filter

Получение всех разделов, созданных в октябре 2014 г.

[GET] ../sections?filter=createdTime ge 2014-10-01 and createdTime le 2014-10-31

Получение страниц, созданных определенным приложением с 1 января 2015 г.

[GET] ../pages?filter=createdByAppId eq 'WLID-0000000048118631' and createdTime ge 2015-01-01

filter и expand

Получение всех страниц определенной записной книжки. По умолчанию API возвращает 20 записей.

[GET] ../pages?filter=parentNotebook/id eq '{notebook-id}'&expand=parentNotebook

Получение имени и ссылки pagesUrl для всех разделов в записной книжке School. При сравнении строк OData учитывается регистр, поэтому рекомендуем использовать функцию tolower.

[GET] ../notebooks?filter=tolower(name) eq 'school'&expand=sections(select=name,pagesUrl)

filter, select и orderby

Получение имени и ссылки pagesUrl для всех разделов, имена которых содержат термин spring. Упорядочивание разделов по дате последнего изменения.

[GET] ../sections?filter=contains(tolower(name),'spring')&select=name,pagesUrl&orderby=lastModifiedTime desc

orderby

Получение первых 20 страниц, отсортированных по свойству createdByAppId и времени создания (по убыванию). По умолчанию API возвращает 20 записей.

[GET] ../pages?orderby=createdByAppId,createdTime desc

фильтр & верхней части

Получите пять новых страниц, созданных с 1 января 2015 г. По умолчанию API возвращает 20 записей. Максимальное количество записей — 100. По умолчанию для страниц используется порядок сортировки lastModifiedTime desc.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5

пропустить & верхней &

Получите следующие пять страниц в результирующем наборе .

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=5

А затем — следующие пять.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=10

Примечание.

Если и верхний, и фильтр применяются к одному и тому же запросу, результаты включают только те сущности, которые соответствуют обоим критериям.

select

Получение имени, времени создания и ссылки self для всех разделов в записных книжках пользователя.

[GET] ../sections?select=name,createdTime,self

Получение названия, времени создания и клиентских ссылок OneNote для определенной страницы.

[GET] ../pages/{page-id}?select=title,createdTime,links

select, expand и filter (несколько уровней)

Получение имени и ссылки pagesUrl для всех разделов в записной книжке по умолчанию пользователя.

[GET] ../notebooks?select=name&expand=sections(select=name,pagesUrl)&filter=isDefault eq true

top, select и orderby

Получение названия и ссылки self для первых 50 страниц, упорядоченных по названию в алфавитном порядке. По умолчанию API возвращает 20 записей. Максимальное количество записей — 100. По умолчанию для страниц используется порядок сортировки lastModifiedTime desc.

[GET] ../pages?top=50&select=title,self&orderby=title

skip, top, select и orderby

Получение страниц с 51 по 100. По умолчанию API возвращает 20 записей. Максимальное количество записей — 100.

[GET] ../pages?skip=50&top=50&select=title,self&orderby=title

Примечание.

Запросы GET для страниц, которые получают количество записей по умолчанию (то есть они не указывают верхнее выражение), возвращают ссылку @odata.nextLink в ответе, которую можно использовать для получения следующих 20 записей.

Поддерживаемые параметры строки запроса OData

Вы можете настраивать запросы GET к Microsoft Graph, используя параметры строки запроса OData, и получать только нужную информацию. Они также могут повышать производительность, уменьшая количество вызовов службы и размер полезных данных ответа.

Примечание.

Для удобочитаемости в примерах в этой статье не используется кодирование пробелов в виде "%20" в строке запроса URL-адреса: filter=isDefault%20eq%20true

Параметр запроса Пример и описание
count

count=true

Количество объектов в коллекции. Значение возвращается в свойстве @odata.count ответа.
expand

expand=sections,sectionGroups

Свойства навигации, которые следует вернуть в тексте ответа. Для выражений expand поддерживаются следующие свойства:
страницы: parentNotebook, parentSection;
разделы: parentNotebook, parentSectionGroup;
группы разделов: sections, sectionGroups, parentNotebook, parentSectionGroup;
записные книжки: sections, sectionGroups.

По умолчанию запросы GET для страниц разворачивают parentSection и выделяют свойства раздела id, name и self. По умолчанию запросы GET для разделов и групп разделов разворачивают как parentNotebook, так и parentSectionGroup, а также выделяют родительские свойства id, name и self.

Может использоваться для одного объекта или коллекции.
Свойства следует разделять запятыми.
В именах свойств учитывается регистр.
filter

filter=isDefault eq true

Логическое выражение, указывающее, следует ли включать запись в набор результатов. Поддерживаются следующие функции и операторы OData:
— операторы сравнения: eq, ne, gt, ge, lt, le;
— логические операторы: and, or, not;
— строковые функции: contains, endswith, startswith, length, indexof, substring, tolower, toupper, trim, concat.

В случае имен свойств и сравнения строк OData учитывается регистр. Рекомендуем использовать функцию OData tolower для сравнения строк.

Пример: filter=tolower(name) eq 'spring'.
orderby

orderby=title,createdTime desc

Свойства для сортировки с необязательным порядком сортировки asc (по умолчанию) или desc. Вы можете сортировать по любому свойству сущности в запрошенной коллекции.

По умолчанию для записных книжек, разделов и групп разделов используется порядок сортировки name asc, а для страниц — lastModifiedTime desc (сначала отображается последняя измененная страница).

Разделяйте свойства запятыми и указывайте их в порядке применения. В именах свойств учитывается регистр.
select

select=id,title

Возвращаемые свойства. Может использоваться для одного объекта или коллекции. Свойства следует разделять запятыми. В именах свойств учитывается регистр.
skip

skip=10

Количество записей, которое следует пропустить в наборе результатов. Обычно используется для разбиения результатов на страницы.
top

top=50

Количество записей, которое следует вернуть в наборе результатов, до 100. Значение по умолчанию — 20.

В Microsoft Graph также доступен параметр строки запроса pagelevel, с помощью которого можно получить уровень и порядок страниц в родительском разделе. Применяется только к запросам страниц в определенном разделе и запросам определенной страницы.

Примеры

  • GET ../sections/{section-id}/pages?pagelevel=true
  • GET ../pages/{page-id}?pagelevel=true

Поддерживаемые операторы и функции OData

Microsoft Graph поддерживает указанные ниже функции и операторы OData в выражениях filter. Используя выражения OData, помните:

  • Пробелы в строке запроса URL необходимо заменять кодом %20.

                  Пример:filter=isDefault%20eq%20true

  • В случае имен свойств и сравнения строк OData учитывается регистр. Рекомендуем использовать функцию OData tolower для сравнения строк.

                  Пример:filter=tolower(name) eq 'spring'

Оператор сравнения Пример
eq
(равно)		 createdByAppId eq '{app-id}'
ne
(не равно)		 userRole ne 'Owner'
gt
(больше)		 createdTime gt 2014-02-23
ge
(больше или равно)		 lastModifiedTime ge 2014-05-05T07:00:00Z
lt
(меньше)		 createdTime lt 2014-02-23
le
(меньше или равно)		 lastModifiedTime le 2014-02-23

Логический оператор Пример
и createdTime le 2014-01-30 and createdTime gt 2014-01-23
Кроме того: createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}'
not not contains(tolower(title),'school')

Строкова функция Пример
contains contains(tolower(title),'spring')
endswith endswith(tolower(title),'spring')
startswith startswith(tolower(title),'spring')
length length(title) eq 19
indexof indexof(tolower(title),'spring') eq 1
substring substring(tolower(title),1) eq 'spring'
tolower tolower(title) eq 'spring'
toupper toupper(title) eq 'SPRING'
trim trim(tolower(title)) eq 'spring'
concat concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'

Свойства объектов OneNote

Выражения запроса filter, select, expand и orderby могут включать свойства объектов OneNote.

Пример

../sections?filter=createdTime ge 2015-01-01&select=name,pagesUrl&orderby=lastModifiedTime desc

Для имен свойств в выражениях запроса учитывается регистр.

Список свойств и типы свойств см. в следующих статьях документации по API REST Microsoft Graph:

Параметр строки запроса expand можно использовать со следующими свойствами навигации:

  • страницы: parentNotebook, parentSection;
  • разделы: parentNotebook, parentSectionGroup;
  • группы разделов: sections, sectionGroups, parentNotebook, parentSectionGroup;
  • записные книжки: sections, sectionGroups.

Информация о запросах GET и соответствующих ответах

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

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

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

application/json — для объектов OneNote и их наборов.

text/html — для содержимого страницы.

Данные в отклике Описание
Код успешного завершения Код состояния HTTP 200
Текст ответа Представление объекта или набора объектов в формате JSON, HTML-код страницы или двоичные данные файлового ресурса.
Ошибки Если запрос завершается с ошибкой, API возвращает ошибки в объекте @api.diagnostics в тексте ответа.
Заголовок X-CorrelationId GUID, уникальный идентификатор запроса. Это значение можно использовать вместе со значением заголовка Date при устранении неполадок совместно со службой поддержки Майкрософт.

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

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

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

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

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

Разрешения для запросов GET

Чтобы получить содержимое или структуру OneNote, необходимо запросить соответствующие разрешения.

Указанные ниже разрешения позволяют выполнять запросы GET к Microsoft Graph. Выберите минимальный уровень разрешений, необходимый для работы вашего приложения.

Варианты:

  • Notes.read
  • Notes.ReadWrite
  • Notes.ReadWrite.All

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

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