Рекомендации по работе с API OneNote в Microsoft Graph

В этой статье содержатся рекомендации по работе с API OneNote в Microsoft Graph. Эти рекомендации основаны на ответах на распространенные вопросы в Microsoft Q&A и Twitter.

Используйте оператор $select, чтобы выбрать минимальный набор необходимых свойств

Если вам необходимо отправить запрос к ресурсу (например, к разделам в записной книжке), создайте запрос, аналогичный указанному ниже.

GET ~/notebooks/{id}/sections

С его помощью можно получить все свойства разделов. Возможно, вам нужны не все свойства. Вы можете использовать параметр запроса $select, чтобы возвращать только необходимые вам свойства, как показано в примере ниже.

GET ~/notebooks/{id}/sections?$select=id,displayName

Такой же подход применяется к другим API OneNote.

Вместо нескольких запросов к API используйте оператор $expand

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

  • Совершите вызов GET ~/notebooks, чтобы получить список записных книжек.

  • Для каждой полученной записной книжки совершите вызов GET ~/notebooks/{notebookId}/sections, чтобы получить список разделов в ней.

  • Для каждой полученной записной книжки совершите вызов GET ~/notebooks/{notebookId}/sectionGroups, чтобы получить список групп разделов в ней.

  • При необходимости выполните рекурсивные итерации в группах разделов.

Несмотря на то что это будет работать (с несколькими дополнительными последовательными циклическими обращениями к службе), лучше использовать параметр запроса $expand.

GET ~/notebooks?$expand=sections,sectionGroups($expand=sections)

Это дает те же результаты в одном цикле сети с более высокой производительностью.

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

Несмотря на то что Microsoft Graph предоставляет конечную точку для получения всех страниц, это не лучший способ получить все страницы, к которым у пользователя есть доступ. Если у пользователя слишком много разделов, это может привести к задержкам или снижению производительности. Лучше выполнять итерации для каждого раздела, получая страницы отдельно для каждого раздела.

Например, вместо использования этого вызова (это постраничный API, поэтому вам не удастся получить все страницы за один раз):

GET ~/pages

Лучше несколько раз использовать следующий вызов (особенно если вам не нужны все разделы):

GET ~/sections/{id}/pages

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

GET ~/sections/{id}/pages?$select=id,title,createdDateTime&$orderby=createdDateTime