アプリで Microsoft Graph データをページングする

Microsoft Graph に対するクエリの中には、サーバー側のページングを使用したり、1 つの要求におけるページ サイズを限定するために $top クエリ パラメーターを使用したりすることによって、複数のデータ ページを返すものがあります。要求セットが複数ページにまたがる場合、Microsoft Graph は、結果の次のページへの URL が含まれる @odata.nextLink プロパティを応答で返します。

たとえば、次の URL の場合、組織内のすべてのユーザーのうち、$top クエリ パラメーターで指定されたページ サイズ 5 のユーザーを要求します。

https://graph.microsoft.com/v1.0/users?$top=5

結果に 5 人を超えるユーザーが含まれる場合、Microsoft Graph は、最初のページのユーザーに加えて、次のような @odata.nextLink プロパティを返します。

"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=X%274453707 ... 6633B900000000000000000000%27"

この @odata.nextLink プロパティの URL 値を Microsoft Graph に送信することによって、結果の次のページを取得できます。

https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=X%274453707 ... 6633B900000000000000000000%27

その後、Microsoft Graph はすべての結果ページが読み取られるまで、それぞれの応答の @odata.nextLink プロパティ内の次のページのデータへの参照を返します。

重要: 結果の次のページの要求には、@odata.nextLink プロパティの URL 全体を含める必要があります。 クエリの実行対象の API によって、@odata.nextLink URL 値には $skiptoken$skip のいずれかのクエリ パラメーターが入ります。 また、URL には、元の要求にある他のクエリ パラメーターすべても含まれます。 $skiptoken 値または $skip 値を抽出して、別の要求で使用しないでください。

ページング動作は、それぞれの Microsoft Graph API によって異なります。 ページングされたデータを扱う場合には、以下の事柄を考慮してください。

  • API によって、既定および最大のページ サイズが異なる場合があります。
  • ($top クエリ パラメーターを使用して) 対象の API の最大ページ サイズを超えるページ サイズを指定する場合には、API によって動作が異なる可能性があります。 API によっては要求されたページ サイズが無視されることがあります。対象 API の最大ページ サイズに既定で設定されたり、Microsoft Graph によってエラーが返されたりする場合があります。
  • すべてのリソースまたはリレーションシップでページングがサポートされているわけではありません。たとえば、directoryRoles に対するクエリではページングはサポートされていません。これにはロール メンバーおよびロール オブジェクト自体の読み取りも含まれます。
  • ディレクトリ リソースに対してページングする場合、ConsistencyLevel ヘッダーなどの追加のリクエスト ヘッダーは、既定では後続のページ リクエストに含まれません。 これらのヘッダーを後続のリクエストで送信する必要がある場合は、明示的に設定する必要があります。
  • ディレクトリ リソースに対してクエリを実行するときに $count=true クエリ文字列を使用すると、@odata.count プロパティはページングされたデータの最初のページにのみ表示されます。

ページングの詳細

次のビデオでは、Microsoft Graph でのページングについて説明します。