Разбиение данных Microsoft Graph по страницам в приложении

Разбиение по страницам включает запрос или получение данных пакетами. Это метод повышения производительности, который имеет решающее значение для эффективной обработки больших наборов данных и помогает повысить производительность приложения и время отклика Microsoft Graph.

Некоторые запросы GET к Microsoft Graph возвращают несколько страниц данных из-за подкачки на стороне сервера или подкачки на стороне клиента. В этой статье мы рассмотрим, как работает разбиение по страницам в Microsoft Graph и как его можно использовать для оптимизации приложений.

Дополнительные сведения о разбиении на страницы см. в следующем видео.

Как работает разбиение на страницы

Разбиение по страницам на стороне сервера

При разбиении на страницы на стороне сервера служба Microsoft Graph возвращает количество результатов по умолчанию на одной странице без указания клиентом количества результатов, возвращаемых с помощью $top. Например, GET /users конечная точка возвращает значение по умолчанию 100 результатов на одной странице.

При наличии по крайней мере еще одной доступной страницы данных Microsoft Graph возвращает @odata.nextLink свойство в ответе, содержащее URL-адрес следующей страницы результатов. Этот URL-адрес используется для запроса следующей страницы результатов. Microsoft Graph продолжит возвращать ссылку на следующую страницу результатов в @odata.nextLink свойстве с каждым ответом, пока не будет больше страниц результатов для получения. Чтобы прочитать все результаты, необходимо продолжать вызывать Microsoft Graph со свойством @odata.nextLink , возвращаемым в каждом ответе @odata.nextLink , пока свойство не будет возвращено.

Разбиение по страницам на стороне клиента

При разбиении на страницы на стороне клиента клиентское приложение указывает количество результатов, которые microsoft Graph должен вернуть на одной странице с помощью параметров запроса $top, $skip или $skipToken . Поддержка разбиения на страницы на стороне клиента, включая количество результатов, которые клиент может запросить на одной странице, зависит от API и выполняемого запроса. Например, конечная /users точка поддерживает , но не $skipподдерживает $top .

В оставшейся части этой статьи описано, как реализовать разбиение на страницы на стороне клиента.

Реализация подкачки на стороне клиента

В следующем примере показано разбиение на страницы на стороне клиента, где клиент использует $top параметр запроса для запроса до пяти пользователей в клиенте.

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

// 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;
});

mgc users list --top "5"

// 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)

// 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;
});

const options = {
	authProvider,
};

const client = Client.init(options);

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

<?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();

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

# 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)

Если результат содержит больше результатов, Microsoft Graph возвращает @odata.nextLink свойство, аналогичное следующему, а также первую страницу результатов:

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

Используйте весь URL-адрес в свойстве @odata.nextLink в запросе GET, чтобы получить следующую страницу результатов. В зависимости от API, к которому выполняется запрос, @odata.nextLink значение URL-адреса содержит $skiptoken параметр запроса или $skip . Все другие параметры запроса, которые присутствовали в исходном запросе, также кодируются в этом URL-адресе. Не пытайтесь извлечь $skiptoken значение или $skip используйте его в другом запросе.

Для различных API Microsoft Graph характерны свои особенности разбиения по страницам. При работе с страничными данными учитывайте следующие моменты:

• Страница результатов может содержать ноль или более результатов.
• Разные API могут иметь различные максимальные размеры страницы и размеры страницы по умолчанию.
• Различные API могут работать по-разному, если указанный (с помощью параметра запроса $top) размер страницы превышает максимальное значение для соответствующего API. Запрошенный размер страницы может быть проигнорирован, по умолчанию — максимальный размер страницы для этого API, или Microsoft Graph может вернуть ошибку.
• Не все ресурсы или связи поддерживают разбиение по страницам. Например, запросы к directoryRole не поддерживают разбиение по страницам. Сюда входит чтение самих объектов ролей и членов роли.
• При разбиении по страницам ресурсов каталога все настраиваемые заголовки запросов (заголовки, которые не являются заголовками авторизации или типа контента), такие как заголовок ConsistencyLevel , по умолчанию не включаются в последующие запросы страницы. Если эти заголовки требуется отправлять в последующие запросы, их необходимо явно настроить.
• При использовании $count=true строки запроса при запросе к ресурсам@odata.count каталога свойство возвращается только на первой странице страничного результированного набора.

Связанные материалы

• Пакеты SDK для Microsoft Graph предоставляют классы и методы, помогающие с разбиением по страницам. Дополнительные сведения см. в разделе Страница через коллекцию с помощью пакетов SDK Для Microsoft Graph.