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.

Observação

Se estiver à procura de informações sobre paginação nos SDKs do Microsoft Graph, consulte Page through a collection using the Microsoft Graph SDKs (Página através de uma coleção com os SDKs do Microsoft Graph).

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.

HTTP

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

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

CLI

mgc users list --top "5"

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

Ir

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância authProvider .

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.

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