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

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

$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 では、すべてのページを取得するためのエンドポイントが公開されます。ただし、このエンドポイントを使用して、ユーザーがアクセスできるすべてのページを取得することはお勧めしません。 ユーザーにセクションが多すぎてすべてのページを取得しようとすると、HTTP 状態コード 400 が生成され、次のメッセージが表示されます。"この要求に対してセクションの最大数を超えています。 セクション数が多いアカウントのページを取得するには、一度に 1 つのセクションのページを取得することをお勧めします。このエラー コードの詳細については、「 OneNote エラー コード」を参照してください。

ユーザーがアクセスできるすべてのページを取得するには、セクションごとに個別の呼び出しを行ってページを取得することをお勧めします。

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

GET ~/pages

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

GET ~/sections/{id}/pages

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

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