Microsoft Graph で OneNote API を使用する場合のベスト プラクティス
この記事では、Microsoft Graph で OneNote API を使用するための推奨事項を提供します。 これらの推奨事項は、 Microsoft Q&A に関する一般的な質問に対する回答に基づいています。
リソース (たとえば、ノートブック内のセクション) のクエリを実行するときには、次のような要求を行います。
GET ~/notebooks/{id}/sections
この要求は、セクションのすべてのプロパティを取得します。 ただし、すべてのプロパティが必要とは限りません。 次の例のように、$select
クエリ パラメーターを使用して、必要なプロパティだけを返すことができます。
GET ~/notebooks/{id}/sections?$select=id,displayName
同じアプローチは、他の OneNote API に適用されます。
ユーザーのノートブック、セクション、およびセクション グループのすべてを階層的なビューで取得します。 次の方法でこれを行います。
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