Pagination des données Microsoft Graph dans votre application

La pagination implique la demande ou la réception de données par lots. Il s’agit d’une technique de performances cruciale pour gérer efficacement les jeux de données volumineux et qui permet d’améliorer les performances de votre application et le temps de réponse de Microsoft Graph.

Certaines requêtes GET sur Microsoft Graph retournent plusieurs pages de données en raison de la pagination côté serveur ou de la pagination côté client. Dans cet article, nous explorons le fonctionnement de la pagination pour Microsoft Graph et comment vous pouvez l’utiliser pour optimiser vos applications.

Remarque

Si vous recherchez des informations sur la pagination dans les Kits de développement logiciel (SDK) Microsoft Graph, consultez Page dans une collection à l’aide des KITS de développement logiciel (SDK) Microsoft Graph.

Pour en savoir plus sur la pagination, consultez la vidéo suivante.

Fonctionnement de la pagination

Pagination côté serveur

Dans la pagination côté serveur, le service Microsoft Graph retourne un nombre par défaut de résultats dans une seule page sans que le client spécifie le nombre de résultats à retourner à l’aide $topde . Par exemple, le GET /users point de terminaison retourne une valeur par défaut de 100 résultats dans une seule page.

Lorsqu’au moins une page de données supplémentaire est disponible, Microsoft Graph renvoie une @odata.nextLink propriété dans la réponse qui contient une URL vers la page de résultats suivante. Vous utilisez cette URL pour interroger la page de résultats suivante. Microsoft Graph continuera à renvoyer une référence à la page de résultats suivante dans la @odata.nextLink propriété avec chaque réponse jusqu’à ce qu’il n’y ait plus de pages de résultats à récupérer. Pour lire tous les résultats, vous devez continuer à appeler Microsoft Graph avec la @odata.nextLink propriété retournée dans chaque réponse jusqu’à ce que la @odata.nextLink propriété ne soit plus retournée.

Pagination côté client

Dans la pagination côté client, une application cliente spécifie le nombre de résultats qu’elle souhaite que Microsoft Graph retourne dans une seule page à l’aide des paramètres de requête $top, $skip ou $skipToken . La prise en charge de la pagination côté client, y compris le nombre de résultats que le client peut demander dans une seule page dépend de l’API et de la requête en cours d’exécution. Par exemple, le point de /users terminaison prend en charge $top mais pas $skip.

Le reste de cet article explique comment implémenter la pagination côté client.

Implémentation de la pagination côté client

L’exemple suivant montre la pagination côté client où le client utilise le $top paramètre de requête pour demander jusqu’à cinq utilisateurs dans le locataire.

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

mgc users list --top "5"

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Si le résultat contient plus de résultats, Microsoft Graph renvoie une @odata.nextLink propriété similaire à la suivante, ainsi que la première page de résultats :

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

Utilisez l’URL entière de la @odata.nextLink propriété dans une requête GET pour récupérer la page de résultats suivante. Selon l’API sur laquelle la requête est exécutée, la @odata.nextLink valeur d’URL contient un $skiptoken paramètre de requête ou .$skip Tous les autres paramètres de requête présents dans la requête d’origine sont également encodés dans cette URL. N’essayez pas d’extraire la valeur ou et $skip de l’utiliser $skiptoken dans une autre requête.

Le comportement de pagination varie en fonction des différentes API Microsoft Graph. Lorsque vous travaillez avec des données paginées, tenez compte des points suivants :

• Une page de résultats peut contenir zéro ou plusieurs résultats.
• Des API différentes peuvent avoir des tailles de page par défaut et maximale différentes.
• Des API différentes peuvent se comporter différemment si vous spécifiez une taille de page (via le paramètre de requête $top) qui dépasse la taille de page maximale pour cette API. La taille de page demandée peut être ignorée, elle peut être définie par défaut sur la taille de page maximale pour cette API, ou Microsoft Graph peut retourner une erreur.
• Toutes les ressources ou relations ne prennent pas en charge la pagination. Par exemple, les requêtes sur directoryRole ne prennent pas en charge la pagination. Cela inclut la lecture des objets de rôle eux-mêmes et des membres de rôle.
• Lors de la pagination par rapport aux ressources d’annuaire, les en-têtes de requête personnalisés (en-têtes qui ne sont pas des en-têtes Authorization ou Content-Type), tels que l’en-tête ConsistencyLevel , ne sont pas inclus par défaut dans les demandes de page suivantes. Si ces en-têtes doivent être envoyés sur les requêtes suivantes, vous devez les définir de manière explicite.
• Lorsque vous utilisez la $count=true chaîne de requête lors de l’interrogation sur des ressources d’annuaire, la @odata.count propriété est retournée uniquement dans la première page du jeu de résultats paginé.

Contenu connexe

• Les sdk Microsoft Graph fournissent des classes et des méthodes pour faciliter la pagination. Pour plus d’informations, consultez Parcourir une collection à l’aide des Kits de développement logiciel (SDK) Microsoft Graph.