Рекомендации по работе с API OneNote в Microsoft GraphBest practices for working with the OneNote API in Microsoft Graph

В этой статье содержатся рекомендации по работе с API OneNote в Microsoft Graph.This article provides recommendations for working with the OneNote APIs in Microsoft Graph. Они основаны на ответах на часто задаваемые вопросы, публикуемые на Stack Overflow и в Twitter.These recommendations are based on answers to common questions on Stack Overflow and Twitter.

Используйте оператор $select, чтобы выбрать минимальный набор необходимых свойствUse $select to select the minimum set of properties you need

Если вам необходимо отправить запрос к ресурсу (например, к разделам в записной книжке), создайте запрос, аналогичный указанному ниже.When you query for a resource (for example, sections inside a notebook), you make a request similar to the following.

GET ~/notebooks/{id}/sections

С его помощью можно получить все свойства разделов.This retrieves all the properties of the sections. Возможно, вам нужны не все свойства.However, you might not need all properties. Вы можете использовать параметр запроса $select, чтобы возвращать только необходимые вам свойства, как показано в примере ниже.You can use the $select query parameter to return just the properties that you want, as shown in the following example.

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

Такой же подход применяется к другим API OneNote.The same approach applies to other OneNote APIs.

Вместо нескольких запросов к API используйте оператор $expandUse $expand instead of making multiple API calls

Предположим, вы хотите получить все записные книжки, разделы и группы разделов пользователя в виде иерархического представления.Suppose you want to retrieve all of the user’s notebooks, sections, and section groups in a hierarchical view. Это можно сделать следующим образом:You might accomplish that by doing the following:

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

  • Для каждой полученной записной книжки совершите вызов GET ~/notebooks/{notebookId}/sections, чтобы получить список разделов в ней.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sections to retrieve the list of sections.

  • Для каждой полученной записной книжки совершите вызов GET ~/notebooks/{notebookId}/sectionGroups, чтобы получить список групп разделов в ней.For every retrieved notebook, call GET ~/notebooks/{notebookId}/sectionGroups to retrieve the list of section groups.

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

Несмотря на то что это будет работать (с несколькими дополнительными последовательными циклическими обращениями к службе), лучше использовать параметр запроса $expand.While this will work (with a few extra sequential roundtrips to the service), a better approach is to use the $expand query parameter.

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

Он даст те же результаты за одно циклическое обращение по сети, но с более высокой производительностью.This will yield the same results in one network roundtrip, with better performance.

При получении всех страниц для пользователя выполните эти действия отдельно для каждого разделаWhen getting all pages for a user, do so for each section separately

Несмотря на то что Microsoft Graph предоставляет конечную точку для получения всех страниц, это не лучший способ получить все страницы, к которым у пользователя есть доступ.While Microsoft Graph exposes an endpoint to retrieve all pages, this isn't the best way to get all the pages the user has access to. Если у пользователя слишком много разделов, это может привести к задержкам или снижению производительности.When the user has too many sections, this can lead to timeouts or bad performance. Лучше выполнять итерации для каждого раздела, получая страницы отдельно для каждого раздела.It is better to iterate each section, getting pages for each one separately.

Например, вместо использования этого вызова (это постраничный API, поэтому вам не удастся получить все страницы за один раз):For example, instead of using this call (this API is paged, so you won't be able to fetch the pages all at once):

GET ~/pages

Лучше несколько раз использовать следующий вызов (особенно если вам не нужны все разделы):It is better to use the following call several times (especially if you don't need all sections):

GET ~/sections/{id}/pages

При получении метаданных страницы переопределите способ упорядочивания lastModifiedDateTime, используемый по умолчанию.When getting page metadata, override the default lastModifiedDateTime ordering. Страницы можно получить быстрее, если не нужно сортировать их по lastModifiedDateTime.It is faster to get pages when you don't have to sort them by lastModifiedDateTime. Для этого вы можете выполнить сортировку по любому другому свойству. Пример:To do this, you can sort by any other property; for example:

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