Paginación de los datos de Microsoft Graph en la aplicación

Algunas consultas GET en Microsoft Graph devuelven varias páginas de datos debido a la paginación del lado servidor o a la paginación del lado cliente. La paginación de datos ayuda a mejorar el rendimiento de la aplicación y el tiempo de respuesta de Microsoft Graph.

Obtenga más información sobre la paginación a través del siguiente vídeo.

Cómo funciona la paginación

En la paginación del lado cliente, una aplicación cliente especifica el número de resultados que quiere que Microsoft Graph devuelva en una sola página mediante los parámetros de consulta $top, $skip o $skipToken . La compatibilidad con la paginación del lado cliente, incluido el número de resultados que el cliente puede solicitar en una sola página, depende de la API y de la consulta que se realice. Por ejemplo, el punto de /users conexión admite $top pero no $skip.

En la paginación del lado servidor, el servicio Microsoft Graph devuelve un número predeterminado de resultados en una sola página sin que el cliente especifique el número de resultados que se devolverán mediante $top. Por ejemplo, el GET /users punto de conexión devuelve un valor predeterminado de 100 resultados en una sola página.

Cuando se requiere más de una solicitud de consulta para recuperar todos los resultados, Microsoft Graph devuelve una @odata.nextLink propiedad en la respuesta que contiene una dirección URL a la página siguiente de resultados. Para recuperar la siguiente página de resultados, se envía el valor de dirección URL de la propiedad @odata.nextLink a Microsoft Graph. Microsoft Graph seguirá devolviendo una referencia a la siguiente página de resultados de la @odata.nextLink propiedad con cada respuesta hasta que no haya más páginas de resultados que recuperar. Para leer todos los resultados, debe seguir llamando a Microsoft Graph con la @odata.nextLink propiedad devuelta en cada respuesta hasta @odata.nextLink que la propiedad ya no se devuelva.

Por ejemplo, en el ejemplo siguiente se muestra la paginación del lado cliente donde el cliente usa el parámetro de $top consulta para solicitar hasta cinco usuarios en el 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;
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de 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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de 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;
});

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de 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();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de 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)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Si el resultado contiene más resultados, Microsoft Graph devuelve una @odata.nextLink propiedad similar a la siguiente junto con la primera página de resultados:

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

Debe incluir toda la dirección URL en la propiedad en la @odata.nextLink solicitud para la siguiente página de resultados. En función de la API en la que se realice la consulta, el valor de dirección @odata.nextLink URL contiene un $skiptoken parámetro de consulta o $skip . La dirección URL contiene también todos los demás parámetros de consulta presentes en la solicitud original. No intente extraer el $skiptoken valor o $skip y úselo en una solicitud diferente.

El comportamiento de paginación varía entre las distintas API de Microsoft Graph. Al trabajar con datos paginados tenga en cuenta lo siguiente:

• Una página de resultados puede contener cero resultados o más.
• Las distintas API pueden tener tamaños de página predeterminados y máximos diferentes.
• Las distintas API pueden comportarse de forma diferente si se especifica un tamaño de página (a través del parámetro de consulta $top) que supera el tamaño máximo de página para la API. Según la API, se puede omitir el tamaño de página solicitado, se puede usar el tamaño de página máximo predeterminado para la API o Microsoft Graph puede devolver un error.
• No todos los recursos o relaciones admiten la paginación. Por ejemplo, las consultas en directoryRole no admiten la paginación. Esto incluye la lectura de los propios objetos de rol y los miembros del rol.
• Al paginar con recursos de directorio, los encabezados de solicitud personalizados (encabezados que no son encabezados Authorization o Content-Type), como el encabezado ConsistencyLevel , no se incluyen de forma predeterminada en las solicitudes de página posteriores. Si es necesario enviar esos encabezados en solicitudes posteriores, debe establecerlos explícitamente.
• Cuando se usa la $count=true cadena de consulta al realizar consultas en recursos de directorio, la @odata.count propiedad solo se devuelve en la primera página del conjunto de resultados paginado.

Contenido relacionado

• Los SDK de Microsoft Graph proporcionan clases y métodos para ayudar con la paginación. Para obtener más información, consulte Página a través de una colección mediante los SDK de Microsoft Graph.