Partager via

Parcourir une collection à l’aide des Kits de développement logiciel (SDK) Microsoft Graph

Pour des raisons de performances, les collections d’entités sont souvent divisées en pages et chaque page est retournée avec une URL vers la page suivante. La classe PageIterator simplifie l’utilisation des collections paginées. PageIterator gère l’énumération de la page active et demande automatiquement les pages suivantes.

Vous pouvez également utiliser la @odata.nextLink propriété pour demander manuellement les pages suivantes.

En-têtes de demande

Si vous envoyez des en-têtes de requête supplémentaires dans votre demande initiale, ces en-têtes 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.

Itérer sur tous les messages

L’exemple suivant montre une itération sur tous les messages dans la boîte aux lettres d’un utilisateur.

Conseil

Cet exemple montre comment définir une petite taille de page à l’aide du top paramètre à des fins de démonstration. Vous pouvez définir la taille de page jusqu’à 999 pour réduire le nombre de demandes nécessaires.

var messages = await graphClient.Me.Messages
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Top = 10;
        requestConfiguration.QueryParameters.Select =
            ["sender", "subject", "body"];
        requestConfiguration.Headers.Add(
            "Prefer", "outlook.body-content-type=\"text\"");
    });

if (messages == null)
{
    return;
}

var pageIterator = PageIterator<Message, MessageCollectionResponse>
    .CreatePageIterator(
        graphClient,
        messages,
        // Callback executed for each item in
        // the collection
        (msg) =>
        {
            Console.WriteLine(msg.Subject);
            return true;
        },
        // Used to configure subsequent page
        // requests
        (req) =>
        {
            // Re-add the header to subsequent requests
            req.Headers.Add("Prefer", "outlook.body-content-type=\"text\"");
            return req;
        });

await pageIterator.IterateAsync();

Arrêt et reprise de l’itération

Certains scénarios nécessitent l’arrêt du processus d’itération pour effectuer d’autres actions. Il est possible de suspendre l’itération en retournant false à partir du rappel d’itération. L’itération peut être reprise en appelant la resume méthode sur le PageIterator.

int count = 0;
int pauseAfter = 25;

var messages = await graphClient.Me.Messages
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Top = 10;
        requestConfiguration.QueryParameters.Select =
            ["sender", "subject"];
    });

if (messages == null)
{
    return;
}

var pageIterator = PageIterator<Message, MessageCollectionResponse>
    .CreatePageIterator(
        graphClient,
        messages,
        (msg) =>
        {
            Console.WriteLine(msg.Subject);
            count++;
            // If we've iterated over the limit,
            // stop the iteration by returning false
            return count < pauseAfter;
        });

await pageIterator.IterateAsync();

while (pageIterator.State != PagingState.Complete)
{
    Console.WriteLine("Iteration paused for 5 seconds...");
    await Task.Delay(5000);
    // Reset count
    count = 0;
    await pageIterator.ResumeAsync();
}

Demande manuelle des pages suivantes

En guise d’alternative à l’utilisation de la classe PageIterator, vous pouvez case activée manuellement la réponse d’une @odata.nextLink propriété et demander la page suivante.

var messages = await graphClient.Me.Messages
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Top = 10;
    });

while (messages?.Value != null)
{
    foreach (var message in messages.Value)
    {
        Console.WriteLine(message.Subject);
    }

    // If OdataNextLink has a value, there is another page
    if (!string.IsNullOrEmpty(messages.OdataNextLink))
    {
        // Pass the OdataNextLink to the WithUrl method
        // to request the next page
        messages = await graphClient.Me.Messages
            .WithUrl(messages.OdataNextLink)
            .GetAsync();
    }
    else
    {
        // No more results, exit loop
        break;
    }
}

Gestion des erreurs

Éviter les erreurs DirectoryPageTokenNotFoundException

Lors de la pagination dans de grands ensembles de données, vous pouvez rencontrer l’erreur DirectoryPageTokenNotFoundException , ce qui empêche l’application cliente de récupérer correctement les pages suivantes. Cette erreur se produit lorsque l’application cliente utilise un jeton d’une opération de nouvelle tentative pour demander la page de résultats suivante.

Pour éviter cette erreur, n’utilisez pas de jetons d’opérations de nouvelle tentative pour les demandes de page suivantes, car ces jetons ne sont pas garantis comme valides pour les demandes futures. Au lieu de cela, conservez le jeton de la dernière réponse réussie et utilisez-le pour la requête de page suivante. Par conséquent, la @odata.nextLink valeur utilisée pour la nouvelle tentative doit être utilisée pour la demande de page suivante.

Exemple de scénario

  1. Récupérez la page 1 et recevez un jeton « Token1 ».
  2. Utilisez « Token1 » pour demander la page 2.
  3. Si vous rencontrez une erreur réseau, réessayez la demande.
  4. Pendant la nouvelle tentative, vous recevez un nouveau jeton « RetryToken ».
  5. N’utilisez pas « RetryToken » pour demander la page 3, car cela peut provoquer l’erreur DirectoryPageTokenNotFoundException .
  6. Utilisez plutôt « Token1 » (le jeton de la dernière réponse de non-nouvelle tentative réussie) pour demander la page 3.