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

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

Используйте оператор $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 предоставляет конечную точку для получения всех страниц; однако мы не рекомендуем использовать эту конечную точку для получения всех страниц, к которые имеет доступ пользователь. Если у пользователя слишком много разделов и предпринята попытка получить все страницы, вызов приводит к коду 400 состояния HTTP и следующему сообщению: "Превышено максимальное количество разделов для этого запроса. Чтобы получить страницы для учетных записей с большим количеством разделов, рекомендуется получать страницы для одного раздела за раз. Дополнительные сведения об этом коде ошибки см. в статье Коды ошибок OneNote.

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

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

GET ~/pages

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

GET ~/sections/{id}/pages

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

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