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

A paginação envolve pedir ou receber dados em lotes. É uma técnica de desempenho crucial para processar eficazmente grandes conjuntos de dados e que ajuda a melhorar o desempenho da sua aplicação e o tempo de resposta do Microsoft Graph.

Algumas consultas GET no Microsoft Graph devolvem múltiplas páginas de dados devido à paginação do lado do servidor ou à paginação do lado do cliente. Neste artigo, vamos explorar como funciona a paginação para o Microsoft Graph e como pode utilizá-la para otimizar as suas aplicações.

Saiba mais sobre a paginação através do seguinte vídeo.

Como funciona a paginação

Paginação do lado do servidor

Na paginação do lado do servidor, o serviço Microsoft Graph devolve um número predefinido de resultados numa única página sem que o cliente especifique o número de resultados a devolver com $top. Por exemplo, o GET /users ponto final devolve uma predefinição de 100 resultados numa única página.

Quando existe pelo menos mais uma página de dados disponíveis, o Microsoft Graph devolve uma @odata.nextLink propriedade na resposta que contém um URL para a página seguinte dos resultados. Utilize este URL para consultar a próxima página de resultados. O Microsoft Graph continuará a devolver uma referência à próxima página de resultados na @odata.nextLink propriedade com cada resposta até que não existam mais páginas de resultados a obter. Para ler todos os resultados, tem de continuar a chamar o Microsoft Graph com a @odata.nextLink propriedade devolvida em cada resposta até que a @odata.nextLink propriedade deixe de ser devolvida.

Paginação do lado do cliente

Na paginação do lado do cliente, uma aplicação cliente especifica o número de resultados que pretende que o Microsoft Graph devolva numa única página com 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 pedir numa única página, depende da API e da consulta que está a ser executada. Por exemplo, o /users ponto final suporta $top , mas não $skip.

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

Implementar paginação do lado do cliente

O exemplo seguinte mostra a paginação do lado do cliente onde o cliente utiliza o $top parâmetro de consulta para pedir até cinco utilizadores no inquilino.

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 devolve 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"

Utilize o URL completo na @odata.nextLink propriedade num pedido GET para obter a página seguinte dos resultados. Consoante a API em que a consulta está a ser executada, o valor do @odata.nextLink URL contém um $skiptoken parâmetro de consulta ou .$skip Todos os outros parâmetros de consulta presentes no pedido original também são codificados neste URL. Não tente extrair o valor ou $skip e utilize-o $skiptoken num pedido 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 da página pedido pode ser ignorado, pode ser predefinido para o tamanho máximo de página dessa API ou o Microsoft Graph pode devolver um erro.
• Nem todos os recursos ou relações suportam paginação. Por exemplo, as consultas no diretórioRole não suportam paginação. Isto inclui a leitura de objetos de função e membros da função.
• Ao paginar os recursos de diretório, os cabeçalhos de pedido personalizados (cabeçalhos que não sejam cabeçalhos de Autorização ou Tipo de Conteúdo), como o cabeçalho ConsistencyLevel , não são incluídos por predefinição nos pedidos de página subsequentes. Se esses cabeçalhos precisam ser enviados em solicitações subsequentes, você deve defini-los explicitamente.
• Ao utilizar a $count=true cadeia de consulta ao consultar recursos de diretório, a @odata.count propriedade é devolvida apenas na primeira página do conjunto de resultados paginado.

Tratamento de erros

Evitar erros directoryPageTokenNotFoundException

Ao paginar grandes conjuntos de dados, poderá deparar-se com o erro, o DirectoryPageTokenNotFoundException que impede a aplicação cliente de obter com êxito as páginas subsequentes. Este erro ocorre quando a aplicação cliente utiliza um token de uma operação de repetição para pedir a página seguinte de resultados.

Para evitar este erro, não utilize tokens de operações de repetição para pedidos de página subsequentes, uma vez que estes tokens não são garantidos como válidos para pedidos futuros. Em vez disso, mantenha o token da última resposta bem-sucedida e utilize-o para o pedido de página seguinte. Por conseguinte, o @odata.nextLink valor utilizado para a repetição deve ser utilizado para o pedido de página subsequente.

Cenário de exemplo

1. Obtenha a Página 1 e receba um token "Token1".
2. Utilize "Token1" para pedir a Página 2.
3. Se encontrar um erro de rede, repita o pedido.
4. Durante a repetição, recebe um novo token "RetryToken".
5. Não utilize "RetryToken" para pedir a Página 3, pois pode causar o DirectoryPageTokenNotFoundException erro.
6. Em vez disso, utilize "Token1" (o token da última resposta sem repetição bem-sucedida) para pedir a Página 3.

Conteúdo relacionado

• Os SDKs do Microsoft Graph fornecem classes e métodos para ajudar na paginação. Para obter detalhes, consulte Page through a collection using the Microsoft Graph SDKs (Página através de uma coleção com os SDKs do Microsoft Graph).