Microsoft Graph で OneNote API を使用する場合の推奨事項Best practices for working with the OneNote API in Microsoft Graph

この記事では、Microsoft Graph で OneNote API を使用するための推奨事項を提供します。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

同じアプローチは、他の OneNote API に適用されます。The same approach applies to other OneNote APIs.

複数の API 呼び出しを実行するのではなく、$expand を使用します。Use $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)

これにより、1 回のネットワーク ラウンドトリップで同じ結果が得られ、より良いパフォーマンスが得られます。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