Paging der Microsoft Graph-Daten in Ihrer App

Einige GET-Abfragen für Microsoft Graph geben mehrere Seiten mit Daten zurück, entweder aufgrund von serverseitigem Paging oder clientseitigem Paging. Das Auslagern von Daten trägt dazu bei, die Leistung Ihrer App und die Antwortzeit von Microsoft Graph zu verbessern.

Weitere Informationen zur Paginierung finden Sie im folgenden Video.

Funktionsweise des Pagings

Beim clientseitigen Paging gibt eine Client-App mithilfe der Abfrageparameter $top, $skip oder $skipToken die Anzahl der Ergebnisse an, die Microsoft Graph auf einer einzelnen Seite zurückgeben soll. Die Unterstützung für clientseitiges Paging, einschließlich der Anzahl der Ergebnisse, die der Client auf einer einzelnen Seite anfordern kann, hängt von der API und der ausgeführten Abfrage ab. Der Endpunkt unterstützt $top z. B. /users , aber nicht $skip.

Beim serverseitigen Paging gibt der Microsoft Graph-Dienst eine Standardanzahl von Ergebnissen auf einer einzelnen Seite zurück, ohne dass der Client die Anzahl der zurückzugebenden Ergebnisse mithilfe $topvon angibt. Der Endpunkt gibt beispielsweise GET /users einen Standardwert von 100 Ergebnissen auf einer einzelnen Seite zurück.

Wenn mehr als eine Abfrageanforderung erforderlich ist, um alle Ergebnisse abzurufen, gibt Microsoft Graph eine @odata.nextLink Eigenschaft in der Antwort zurück, die eine URL zur nächsten Ergebnisseite enthält. Sie können die nächste Seite mit Ergebnissen abrufen, indem Sie den URL-Wert der @odata.nextLink-Eigenschaft an Microsoft Graph senden. Microsoft Graph gibt mit jeder Antwort weiterhin einen Verweis auf die nächste Ergebnisseite in der @odata.nextLink -Eigenschaft zurück, bis keine weiteren Ergebnisseiten mehr abgerufen werden. Um alle Ergebnisse zu lesen, müssen Sie Weiterhin Microsoft Graph mit der eigenschaft aufrufen, die @odata.nextLink in jeder Antwort zurückgegeben wird, bis die @odata.nextLink Eigenschaft nicht mehr zurückgegeben wird.

Das folgende Beispiel zeigt z. B. clientseitiges Paging, bei dem der Client den $top Abfrageparameter verwendet, um bis zu fünf Benutzer im Mandanten anzufordern.

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

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

mgc users list --top "5"

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

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

const options = {
	authProvider,
};

const client = Client.init(options);

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

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

Import-Module Microsoft.Graph.Users

Get-MgUser -Top 5 

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

Wenn das Ergebnis mehr Ergebnisse enthält, gibt Microsoft Graph zusammen mit der ersten Ergebnisseite eine @odata.nextLink Eigenschaft ähnlich der folgenden zurück:

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

Verwenden Sie die gesamte URL in der @odata.nextLink -Eigenschaft in einer GET-Anforderung, um die nächste Ergebnisseite abzurufen. Abhängig von der API, für die die Abfrage ausgeführt wird, enthält der @odata.nextLink URL-Wert entweder einen $skiptoken oder einen $skip Abfrageparameter. Die URL enthält auch alle anderen Abfrageparameter, die in der ursprünglichen Anforderung vorhanden sind. Versuchen Sie nicht, den $skiptoken Wert oder $skip zu extrahieren und in einer anderen Anforderung zu verwenden.

Das Paging-Verhalten variiert in den verschiedenen Microsoft Graph-APIs. Berücksichtigen Sie beim Arbeiten mit ausgelagerten Daten die folgenden Punkte:

• Eine Seite mit Ergebnissen kann null oder mehr Ergebnisse enthalten.
• Unterschiedliche APIs weisen möglicherweise unterschiedliche Standard- und Maximalgrößen für Seiten auf.
• Unterschiedliche APIs verhalten sich möglicherweise unterschiedlich, wenn Sie eine Seitengröße (über den $top-Abfrageparameter) angeben, der die maximale Seitengröße für diese API überschreitet. Je nach API wird die angeforderte Seitengröße möglicherweise ignoriert oder standardmäßig auf die maximale Seitengröße für diese API festgelegt, oder Microsoft Graph gibt einen Fehler zurück.
• Nicht alle Ressourcen oder Beziehungen unterstützen Paging. Beispielsweise unterstützen Abfragen für directoryRole kein Paging. Dies schließt das Lesen von Rollenobjekten selbst und Rollenmitgliedern ein.
• Beim Paginieren von Verzeichnisressourcen werden alle benutzerdefinierten Anforderungsheader (header, die keine Authorization- oder Content-Type-Header sind) wie der ConsistencyLevel-Header nicht standardmäßig in nachfolgende Seitenanforderungen eingeschlossen. Wenn diese Header bei nachfolgenden Anforderungen gesendet werden müssen, müssen Sie sie explizit festlegen.
• Wenn Sie die $count=true Abfragezeichenfolge beim Abfragen von Verzeichnisressourcen verwenden, wird die @odata.count Eigenschaft nur auf der ersten Seite des ausgelagerten Resultsets zurückgegeben.

Verwandte Inhalte

• Microsoft Graph SDKs stellen Klassen und Methoden bereit, die beim Paging helfen. Weitere Informationen finden Sie unter Seite durch eine Sammlung mit den Microsoft Graph SDKs.