アプリで Microsoft Graph データをページングする
Microsoft Graph に対する一部の GET クエリでは、サーバー側のページングまたはクライアント側のページングにより、複数ページのデータが返されます。 ページング データは、アプリのパフォーマンスと Microsoft Graph の応答時間を向上させるのに役立ちます。
ページ分割の詳細については、次のビデオを参照してください。
ページングのしくみ
クライアント側のページングでは、クライアント アプリは、$top、$skip、または$skipTokenクエリ パラメーターを使用して、Microsoft Graph が 1 つのページで返す結果の数を指定します。 クライアントが 1 つのページで要求できる結果の数など、クライアント側のページングのサポートは、API と実行されているクエリによって異なります。 たとえば、エンドポイントは を /users
サポートしますが、 は $top
サポートしていません $skip
。
サーバー側のページングでは、Microsoft Graph サービスは、クライアントが を使用して $top
返す結果の数を指定せずに、1 つのページで既定の結果数を返します。 たとえば、エンドポイントは GET /users
既定値の 100 を返し、結果は 1 つのページになります。
すべての結果を取得するために複数のクエリ要求が必要な場合、Microsoft Graph は、結果の次のページへの URL を含むプロパティを応答で返 @odata.nextLink
します。 この @odata.nextLink
プロパティの URL 値を Microsoft Graph に送信することによって、結果の次のページを取得できます。 Microsoft Graph は、取得する結果のページがなくなったまで、各応答を持つプロパティ内 @odata.nextLink
の結果の次のページへの参照を引き続き返します。 すべての結果を読み取るには、プロパティが返されなくなるまで、各応答で返されるプロパティを使用 @odata.nextLink
して Microsoft Graph を @odata.nextLink
引き続き呼び出す必要があります。
たとえば、次の例では、クライアントがクエリ パラメーターを使用 $top
してテナント内の最大 5 人のユーザーを要求するクライアント側ページングを示しています。
GET https://graph.microsoft.com/v1.0/users?$top=5
結果にさらに多くの結果が含まれている場合、Microsoft Graph は結果の @odata.nextLink
最初のページと共に次のようなプロパティを返します。
"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=RFNwdAIAAQAAAD8...AAAAAAAA"
結果の次のページの要求に @odata.nextLink
、プロパティに URL 全体を含める必要があります。 クエリが実行されている API に応じて、@odata.nextLink
URL 値には、 または $skip
クエリ パラメーターが$skiptoken
含まれます。 また、URL には、元の要求にある他のクエリ パラメーターすべても含まれます。 または $skip
値を抽出して別の$skiptoken
要求で使用しないでください。
ページング動作は、それぞれの Microsoft Graph API によって異なります。 ページングされたデータを扱う場合には、以下の事柄を考慮してください。
- 結果のページには、0 または 1 つ以上の結果が含まれます。
- API によって、既定および最大のページ サイズが異なる場合があります。
- (
$top
クエリ パラメーターを使用して) 対象の API の最大ページ サイズを超えるページ サイズを指定する場合には、API によって動作が異なる可能性があります。 API によっては要求されたページ サイズが無視されることがあります。対象 API の最大ページ サイズに既定で設定されたり、Microsoft Graph によってエラーが返されたりする場合があります。 - すべてのリソースまたはリレーションシップがページングをサポートしているわけではありません。 たとえば、 directoryRole に対するクエリではページングはサポートされていません。 これには、ロール オブジェクト自体とロール メンバーの読み取りが含まれます。
- ディレクトリ リソースに対してページングする場合、ConsistencyLevel ヘッダーなどのカスタム要求ヘッダー (Authorization ヘッダーまたは Content-Type ヘッダーではないヘッダー) は、後続のページ要求には既定では含まれません。 これらのヘッダーを後続のリクエストで送信する必要がある場合は、明示的に設定する必要があります。
- ディレクトリ リソースに
$count=true
対してクエリを実行するときにクエリ文字列を使用する場合、@odata.count
プロパティはページ化された結果セットの最初のページでのみ返されます。
関連コンテンツ
- Microsoft Graph SDK には、ページングに役立つクラスとメソッドが用意されています。 詳細については、「 Microsoft Graph SDK を使用したコレクションのページスルー」を参照してください。
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示