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

Получение содержимого и структуры 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",
  "links":{
    "previewImageUrl":{
      "href":"https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png"
    }
  }
}

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

Если на странице есть изображение, подходящее для предварительного просмотра, то свойство href объекта previewImageUrl будет содержать ссылку на общедоступный ресурс изображения. Эту ссылку можно использовать в коде HTML. Если не сделать этого, свойство href возвратит значение NULL.

Пример

<img src="https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png" />

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.

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