アプリで Microsoft Graph データをページングするPaging Microsoft Graph data in your app

Microsoft Graph に対するクエリの中には、サーバー側のページングを使用したり、1 つの要求におけるページ サイズを限定するために $top クエリ パラメーターを使用したりすることによって、複数のデータ ページを返すものがあります。要求セットが複数ページにまたがる場合、Microsoft Graph は、結果の次のページへの URL が含まれる @odata.nextLink プロパティを応答で返します。Some queries against Microsoft Graph return multiple pages of data either due to server-side paging or due to the use of the $top query parameter to specifically limit the page size in a request. When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

たとえば、次の URL の場合、組織内のすべてのユーザーのうち、$top クエリ パラメーターで指定されたページ サイズ 5 のユーザーを要求します。For example, the following URL requests all the users in an organization with a page size of 5, specified with the $top query parameter:

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

結果に 5 人を超えるユーザーが含まれる場合、Microsoft Graph は、最初のページのユーザーに加えて、次のような @odata:nextLink プロパティを返します。If the result contains more than five users, Microsoft Graph will return an @odata:nextLink property similar to the following along with the first page of users.

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

この @odata:nextLink プロパティの URL 値を Microsoft Graph に送信することによって、結果の次のページを取得できます。You can retrieve the next page of results by sending the URL value of the @odata:nextLink property to Microsoft Graph.

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

その後、Microsoft Graph はすべての結果ページが読み取られるまで、それぞれの応答の @odata:nextLink プロパティ内の次のページのデータへの参照を返します。Microsoft Graph will continue to return a reference to the next page of data in the @odata:nextLink property with each response until all pages of the result have been read.

重要: 結果の次のページの要求には、@odata:nextLink プロパティの URL 全体を含める必要があります。Important: You should include the entire URL in the @odata:nextLink property in your request for the next page of results. クエリの実行対象の API によって、@odata:nextLink URL 値には $skiptoken$skip のいずれかのクエリ パラメーターが入ります。Depending on the API that the query is being performed against, the @odata:nextLink URL value will contain either a $skiptoken or a $skip query parameter. また、URL には、元の要求にある他のクエリ パラメーターすべても含まれます。The URL also contains all the other query parameters present in the original request. $skiptoken 値または $skip 値を抽出して、別の要求で使用しないでください。Do not try to extract the $skiptoken or $skip value and use it in a different request.

ページング動作は、それぞれの Microsoft Graph API によって異なります。Paging behavior varies across different Microsoft Graph APIs. ページングされたデータを扱う場合には、以下の事柄を考慮してください。Consider the following when working with paged data:

  • API によって、既定および最大のページ サイズが異なる場合があります。Different APIs might have different default and maximum page sizes.
  • ($top クエリ パラメーターを使用して) 対象の API の最大ページ サイズを超えるページ サイズを指定する場合には、API によって動作が異なる可能性があります。Different APIs might behave differently if you specify a page size (via the $top query parameter) that exceeds the maximum page size for that API. API によっては要求されたページ サイズが無視されることがあります。対象 API の最大ページ サイズに既定で設定されたり、Microsoft Graph によってエラーが返されたりする場合があります。Depending on the API, the requested page size might be ignored, it might default to the maximum page size for that API, or Microsoft Graph might return an error.
  • すべてのリソースまたはリレーションシップでページングがサポートされているわけではありません。たとえば、directoryRoles に対するクエリではページングはサポートされていません。これにはロール メンバーおよびロール オブジェクト自体の読み取りも含まれます。Not all resources or relationships support paging. For example, queries against directoryRoles do not support paging. This includes reading role objects themselves as well as role members.

ページングの詳細Learn more about:

次のビデオでは、Microsoft Graph でのページングについて説明します。The following video introduces you to paging in Microsoft Graph.