Paging der Microsoft Graph-Daten in Ihrer App

Paging umfasst das Anfordern oder Empfangen von Daten in Batches. Es handelt sich um eine Leistungstechnik, die für die effiziente Verarbeitung großer Datasets von entscheidender Bedeutung ist und die Leistung Ihrer App und die Antwortzeit von Microsoft Graph verbessert.

Einige GET-Abfragen für Microsoft Graph geben mehrere Seiten mit Daten zurück, entweder aufgrund von serverseitigem Paging oder clientseitigem Paging. In diesem Artikel erfahren Sie, wie Paging für Microsoft Graph funktioniert und wie Sie es verwenden können, um Ihre Anwendungen zu optimieren.

Weitere Informationen zur Paginierung finden Sie im folgenden Video.

Funktionsweise des Pagings

Serverseitiges Paging

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 mindestens eine weitere Datenseite verfügbar ist, gibt Microsoft Graph eine @odata.nextLink Eigenschaft in der Antwort zurück, die eine URL zur nächsten Ergebnisseite enthält. Sie verwenden diese URL, um die nächste Ergebnisseite abzufragen. 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.

Clientseitiges Paging

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.

Im weiteren Verlauf dieses Artikels wird beschrieben, wie Clientseitiges Paging implementiert wird.

Implementieren von clientseitigem Paging

Das folgende Beispiel zeigt 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;
});

// 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. Alle anderen Abfrageparameter, die in der ursprünglichen Anforderung vorhanden waren, werden ebenfalls in dieser URL codiert. 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 Ergebnisseite 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. Die angeforderte Seitengröße wird möglicherweise ignoriert, die maximale Seitengröße für diese API wird standardmäßig verwendet, 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.

Fehlerbehandlung

Vermeiden von DirectoryPageTokenNotFoundException-Fehlern

Beim Paginieren großer Datenmengen tritt möglicherweise der Fehler auf, der DirectoryPageTokenNotFoundException verhindert, dass die Client-App nachfolgende Seiten erfolgreich abruft. Dieser Fehler tritt auf, wenn die Client-App ein Token aus einem Wiederholungsvorgang verwendet, um die nächste Ergebnisseite anzufordern.

Um diesen Fehler zu vermeiden, verwenden Sie keine Token aus Wiederholungsvorgängen für nachfolgende Seitenanforderungen, da diese Token nicht garantiert für zukünftige Anforderungen gültig sind. Speichern Sie stattdessen das Token aus der letzten erfolgreichen Antwort, und verwenden Sie es für die nächste Seitenanforderung. Daher sollte der @odata.nextLink für die Wiederholung verwendete Wert für die nachfolgende Seitenanforderung verwendet werden.

Beispielszenario

1. Rufen Sie Seite 1 ab, und erhalten Sie das Token "Token1".
2. Verwenden Sie "Token1", um Seite 2 anzufordern.
3. Wenn ein Netzwerkfehler auftritt, wiederholen Sie die Anforderung.
4. Während des Wiederholungsversuchs erhalten Sie das neue Token "RetryToken".
5. Verwenden Sie "RetryToken" nicht, um Seite 3 anzufordern, da dies den DirectoryPageTokenNotFoundException Fehler verursachen kann.
6. Verwenden Sie stattdessen "Token1" (das Token aus der letzten erfolgreichen Antwort ohne Wiederholung), um Seite 3 anzufordern.

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.