Paginação de dados do Microsoft Graph em seu aplicativo

A paginação envolve solicitar ou receber dados em lotes. É uma técnica de desempenho crucial para lidar com eficiência com grandes conjuntos de dados e que ajuda a melhorar o desempenho do seu aplicativo e o tempo de resposta do Microsoft Graph.

Algumas consultas GET no Microsoft Graph retornam várias páginas de dados devido à paginação do lado do servidor ou do lado do cliente. Neste artigo, exploramos como a paginação funciona para o Microsoft Graph e como você pode usá-la para otimizar seus aplicativos.

Saiba mais sobre paginação no vídeo a seguir.

Como funciona a paginação

Paginação do lado do servidor

Na paginação do lado do servidor, o serviço Microsoft Graph retorna um número padrão de resultados em uma única página sem que o cliente especifique o número de resultados a serem retornados usando $top. Por exemplo, o GET /users ponto de extremidade retorna um padrão de 100 resultados em uma única página.

Quando há pelo menos mais uma página de dados disponível, o Microsoft Graph retorna uma @odata.nextLink propriedade na resposta que contém uma URL para a próxima página de resultados. Você usa essa URL para consultar a próxima página de resultados. O Microsoft Graph continuará retornando uma referência para a próxima página de resultados na @odata.nextLink propriedade com cada resposta até que não haja mais páginas de resultados a serem recuperados. Para ler todos os resultados, você deve continuar a chamar o Microsoft Graph com a propriedade retornada @odata.nextLink em cada resposta até que a @odata.nextLink propriedade não seja mais retornada.

Paginação do lado do cliente

Na paginação do lado do cliente, um aplicativo cliente especifica o número de resultados que deseja que o Microsoft Graph retorne em uma única página usando os parâmetros de consulta $top, $skip ou $skipToken . O suporte para paginação do lado do cliente, incluindo o número de resultados que o cliente pode solicitar em uma única página, depende da API e da consulta que está sendo executada. Por exemplo, o /users ponto de extremidade dá suporte $top a mas, não $skip.

O restante deste artigo descreve como implementar a paginação do lado do cliente.

Implementando a paginação do lado do cliente

O exemplo a seguir mostra a paginação do lado do cliente em que o cliente usa o $top parâmetro de consulta para solicitar até cinco usuários no locatário.

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

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

Se o resultado contiver mais resultados, o Microsoft Graph retornará uma @odata.nextLink propriedade semelhante à seguinte, juntamente com a primeira página de resultados:

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

Use a URL inteira na @odata.nextLink propriedade em uma solicitação GET para recuperar a próxima página de resultados. Dependendo da API em que a consulta está sendo executada, o valor da @odata.nextLink URL contém um $skiptoken ou um parâmetro de $skip consulta. Quaisquer outros parâmetros de consulta que estavam presentes na solicitação original também são codificados nessa URL. Não tente extrair o $skiptoken valor OR $skip e usá-lo em uma solicitação diferente.

O comportamento de paginação varia entre diferentes APIs do Microsoft Graph. Considere os seguintes pontos ao trabalhar com dados paginados:

• Uma página de resultados pode conter zero ou mais resultados.
• APIs diferentes podem ter tamanhos padrão e máximo de página diferentes.
• APIs diferentes poderão se comportar de maneira diferente se você especificar um tamanho de página (por meio do parâmetro de consulta $top) que exceda o tamanho máximo de página para essa API. O tamanho de página solicitado pode ser ignorado, o padrão pode ser o tamanho máximo de página para essa API ou o Microsoft Graph pode retornar um erro.
• Nem todos os recursos ou relações são compatíveis com a paginação. Por exemplo, consultas em directoryRole não dão suporte à paginação. Isso inclui a leitura dos próprios objetos de função e dos membros da função.
• Ao paginar em recursos de diretório, todos os cabeçalhos de solicitação personalizados (cabeçalhos que não são cabeçalhos Authorization ou Content-Type), como o cabeçalho ConsistencyLevel , não são incluídos por padrão nas solicitações de paginação subsequentes. Se esses cabeçalhos precisam ser enviados em solicitações subsequentes, você deve defini-los explicitamente.
• Ao usar a $count=true cadeia de caracteres de consulta ao consultar recursos de diretório, a @odata.count propriedade é retornada somente na primeira página do conjunto de resultados paginados.

Tratamento de erros

Evitando erros DirectoryPageTokenNotFoundException

Ao paginar por grandes conjuntos de dados, você pode encontrar o DirectoryPageTokenNotFoundException erro, o que impede que o aplicativo cliente recupere com êxito as páginas subsequentes. Esse erro ocorre quando o aplicativo cliente usa um token de uma operação de repetição para solicitar a próxima página de resultados.

Para evitar esse erro, não use tokens de operações de repetição para solicitações de página subsequentes, pois não há garantia de que esses tokens sejam válidos para solicitações futuras. Em vez disso, mantenha o token da última resposta bem-sucedida e use-o para a próxima solicitação de página. Portanto, o @odata.nextLink valor usado para a repetição deve ser usado para a solicitação de página subsequente.

Cenário de exemplo

1. Recupere a Página 1 e receba um token "Token1".
2. Use "Token1" para solicitar a Página 2.
3. Se você encontrar um erro de rede, repita a solicitação.
4. Durante a nova tentativa, você receberá um novo token "RetryToken".
5. Não use "RetryToken" para solicitar a Página 3, pois isso pode causar o DirectoryPageTokenNotFoundException erro.
6. Em vez disso, use "Token1" (o token da última resposta bem-sucedida de não repetição) para solicitar a Página 3.

Conteúdo relacionado

• Os SDKs do Microsoft Graph fornecem classes e métodos para ajudar com a paginação. Para obter detalhes, consulte Paginar uma coleção usando os SDKs do Microsoft Graph.