Pagination des données Microsoft Graph dans votre application

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. La pagination des données permet d’améliorer les performances de votre application et le temps de réponse de Microsoft Graph.

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

Fonctionnement de la pagination

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.

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.

Lorsque plusieurs requêtes sont nécessaires pour récupérer tous les résultats, Microsoft Graph retourne une @odata.nextLink propriété dans la réponse qui contient une URL vers la page de résultats suivante. Vous pouvez récupérer la page de résultats suivante en envoyant la valeur d’URL de la propriété @odata.nextLink à Microsoft Graph. 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.

Par exemple, 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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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

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)

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

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)

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"

Vous devez inclure l’URL entière dans la @odata.nextLink propriété dans votre demande pour 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 L’URL contient également tous les autres paramètres de requête présents dans la demande d’origine. 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 utilisez des données paginées, prenez en compte les éléments 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. En fonction de l’API, la taille de page demandée peut être ignorée, peut revenir à la taille de page maximale par défaut pour cette API ou Microsoft Graph peut renvoyer 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.