Microsoft Graph で OneNote API を使用する場合のベスト プラクティス

この記事では、Microsoft Graph で OneNote API を使用するための推奨事項を提供します。 これらの推奨事項は、 Microsoft Q&A と Twitter に関する一般的な質問に対する回答に基づいています。

$Select を使用して、必要なプロパティの最小限のセットを選択する

リソース (たとえば、ノートブック内のセクション) のクエリを実行するときには、次のような要求を行います。

GET ~/notebooks/{id}/sections

これは、セクションのすべてのプロパティを取得します。 ただし、すべてのプロパティが必要とは限りません。 次の例のように、$select クエリ パラメーターを使用して、必要なプロパティだけを返すことができます。

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

同じアプローチは、他の OneNote API に適用されます。

複数の API 呼び出しを実行するのではなく、$expand を使用します。

ユーザーのノートブック、セクション、およびセクション グループのすべてを階層的なビューで取得します。 次の方法でこれを行います。

• GET ~/notebooks を呼び出して、ノートブックの一覧を取得します。

• 取得したすべてのノートブックについて、GET ~/notebooks/{notebookId}/sections を呼び出してセクションの一覧を取得します。

• 取得したすべてのノートブックについて、GET ~/notebooks/{notebookId}/sectionGroups を呼び出してセクション グループの一覧を取得します。

• 必要に応じて、セクション グループを再帰的に反復処理できます。

この方法 (サービスへ何回かの連続した余分なラウンドトリップを実行) でも可能ですが、より優れたアプローチは、$expand クエリ パラメーターを使用することです。

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

これにより、1 つのネットワークラウンドトリップで同じ結果が得られます。パフォーマンスが向上します。

ユーザーに対してすべてのページを取得する場合は、セクションごとに個別に行ってください。

Microsoft Graph はすべてのページを取得するためにエンドポイントを公開しますが、これはユーザーがアクセス権を持っているすべてのページを取得する最良の方法ではありません。 ユーザーが持つセクションが多すぎると、これによりタイムアウトやパフォーマンスの低下を招きます。 各セクションを反復処理して、個別にそれぞれのページを取得することをお勧めします。

たとえば、この呼び出しを使用する代わりに、(この API はページ化されているので、すべてのページを一度にフェッチすることはできません):

GET ~/pages

(特にすべてのセクションが必要ない場合は) 次の呼び出しを何回か使用することをお勧めします。

GET ~/sections/{id}/pages

ページのメタデータを取得するには、既定値 lastModifiedDateTime の順序付けを上書きします。 それらを lastModifiedDateTime で並べ替える必要がないときには、より速くページを取得できます。 これを行うには、たとえば他の任意のプロパティで並べ替えることができます。

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