在应用中对 Microsoft Graph 数据进行分页

分页涉及批量请求或接收数据。 这是一种性能技术，对于高效处理大型数据集至关重要，有助于提高应用性能和Microsoft Graph 的响应时间。

由于服务器端分页或客户端分页，针对 Microsoft Graph 的某些 GET 查询返回多页数据。 在本文中，我们将探讨分页如何适用于 Microsoft Graph，以及如何使用它来优化应用程序。

备注

如果要查找有关在 Microsoft Graph SDK 中分页的信息，请参阅 使用 Microsoft Graph SDK 对集合进行分页。

通过以下视频详细了解分页。

分页工作方式

服务器端分页

在服务器端分页中，Microsoft Graph 服务在单个页面中返回默认的结果数，而客户端不使用 指定要返回 $top的结果数。 例如，终结点在 GET /users 单个页面中返回默认值 100 个结果。

当至少有一页数据可用时，Microsoft Graph 在响应中返回一个 @odata.nextLink 属性，该属性包含指向下一页结果的 URL。 使用此 URL 查询下一页结果。 Microsoft Graph 将继续返回对属性中 @odata.nextLink 每个响应中下一页结果的引用，直到没有更多要检索的结果页。 若要读取所有结果，必须继续使用每个响应中返回的属性调用 Microsoft Graph @odata.nextLink ，直到不再返回该 @odata.nextLink 属性。

客户端分页

在客户端分页中，客户端应用使用$top、$skip或$skipToken查询参数指定它希望Microsoft Graph 在单个页面中返回的结果数。 对客户端分页的支持，包括客户端可以在单个页面中请求的结果数取决于 API 和正在执行的查询。 例如， /users 终结点支持 $top 但不支持 $skip。

本文的其余部分介绍如何实现客户端分页。

实现客户端分页

以下示例演示客户端分页，其中客户端使用 $top 查询参数请求租户中最多五个用户。

HTTP

msgraph

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

C#

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Top = 5;
});

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

CLI

Bash

mgc users list --top "5"

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

Go

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestTop := int32(5)

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Top: &requestTop,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

Java

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.top = 5;
});

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

JavaScript

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.top(5)
	.get();

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

PHP

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

PowerShell

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

Python

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		top = 5,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

请阅读 SDK 文档，了解如何将 SDK 添加到项目并创建 authProvider 实例的详细信息。

如果结果包含更多结果，Microsoft Graph 将 @odata.nextLink 返回如下所示的属性以及结果的第一页：

JSON

"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=RFNwdAIAAQAAAD8...AAAAAAAA"

在 GET 请求中使用 属性中的 @odata.nextLink 整个 URL 来检索下一页结果。 根据要对其执行查询的 API，URL @odata.nextLink 值包含 $skiptoken 或 $skip 查询参数。 原始请求中存在的任何其他查询参数也在此 URL 中编码。 请勿尝试提取 $skiptoken 或 $skip 值并在其他请求中使用它。

分页行为因 Microsoft Graph API 不同而异。 使用分页数据时，请考虑以下几点：

• 结果页可能包含零个或多个结果。
• 不同的 API 可能具有不同的默认页面大小和最大页面大小。
• 如果指定超过相应 API 最大页面大小的页面大小（通过 $top 查询参数），则不同 API 的行为会有所不同。 请求的页面大小可能会被忽略，它可能默认为该 API 的最大页面大小，或者Microsoft Graph 可能会返回错误。
• 并非所有资源或关系都支持分页。 例如，针对 directoryRole 的查询不支持分页。 这包括读取角色对象本身和角色成员。
• 当对 目录资源进行分页时，任何自定义请求标头 (不是 Authorization 或 Content-Type 标头) （如 ConsistencyLevel 标头）默认情况下不会包含在后续页面请求中。 如果需要在后续请求中发送这些标头，则必须显式设置它们。
• 在对目录资源进行查询时使用$count=true查询字符串时，@odata.count属性仅在分页结果集的第一页中返回。

相关内容

• Microsoft Graph SDK 提供类和方法来帮助分页。 有关详细信息，请参阅 使用 Microsoft Graph SDK 对集合进行分页。