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

Algumas consultas GET no Microsoft Graph retornam várias páginas de dados devido à paginação do lado do servidor ou paginação do lado do cliente. A paginação de dados ajuda a melhorar o desempenho do seu aplicativo e o tempo de resposta do Microsoft Graph.

Saiba mais sobre paginação por meio do vídeo a seguir.

Como funciona a paginação

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á $top suporte, mas não $skip.

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 mais de uma solicitação de consulta é necessária para recuperar todos os resultados, o Microsoft Graph retorna uma @odata.nextLink propriedade na resposta que contém uma URL para a próxima página de resultados. Você pode recuperar a próxima página de resultados enviando o valor de URL da propriedade @odata.nextLink para o Microsoft Graph. O Microsoft Graph continuará retornando uma referência à 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 @odata.nextLink propriedade retornada em cada resposta até que a @odata.nextLink propriedade não seja mais retornada.

Por exemplo, 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.

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 seu projeto e criar uma instância do authProvider .

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --top "5"

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

Ir

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestTop := int32(5)

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

users, err := graphClient.Users().Get(context.Background(), configuration)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do 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 seu projeto e criar uma instância do authProvider .

Python

from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		top = 5,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
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 seu projeto e criar uma instância do authProvider .

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"

Você deve incluir toda a URL na @odata.nextLink propriedade em sua solicitação para 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. A URL também contém todos os outros parâmetros de consulta presentes na solicitação original. Não tente extrair o $skiptoken valor ou $skip e usá-lo em uma solicitação diferente.

O comportamento de paginação varia entre diferentes APIs do Microsoft Graph. Ao trabalhar com dados paginados, considere o seguinte:

• 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. Dependendo da API, o tamanho de página solicitado pode ser ignorado, ele pode usar por padrão 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 dão suporte à paginação. Por exemplo, consultas contra directoryRole não dão suporte à paginação. Isso inclui a leitura de objetos de função e membros da função.
• Ao paginar em relação aos recursos de diretório, os cabeçalhos de solicitação personalizados (cabeçalhos que não são cabeçalhos de Tipo de Conteúdo ou Autorização) como o cabeçalho ConsistencyLevel não são incluídos por padrão em solicitações de página 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 em relação aos recursos de diretório, a @odata.count propriedade é retornada somente na primeira página do conjunto de resultados paged.

Conteúdo relacionado

• Os SDKs do Microsoft Graph fornecem classes e métodos para ajudar na paginação. Para obter detalhes, confira Página por meio de uma coleção usando os SDKs do Microsoft Graph.