En utilisant les résultats paginés dans AWS SDK pour .NET

Certains AWS services collectent et stockent une grande quantité de données, que vous pouvez récupérer à l'aide des appels d'API du AWS SDK pour .NET. Si la quantité de données que vous souhaitez récupérer devient trop importante pour un seul appel d'API, vous pouvez diviser les résultats en éléments plus faciles à gérer en utilisant la pagination.

Pour vous permettre d'effectuer la pagination, les objets de requête et de réponse de nombreux clients de service du SDK fournissent un jeton de continuation (généralement nomméNextToken). Certains de ces clients de services fournissent également des paginateurs .

Les paginateurs vous permettent d'éviter la surcharge du jeton de continuation, qui peut impliquer des boucles, des variables d'état, plusieurs appels d'API, etc. Lorsque vous utilisez un paginateur, vous pouvez récupérer les données d'un AWS service via une seule ligne de code, la déclaration d'une foreach boucle. Si plusieurs appels d'API sont nécessaires pour récupérer les données, le paginateur s'en charge pour vous.

Où puis-je trouver des paginateurs ?

Tous les services ne proposent pas de paginateurs. L'un des moyens de déterminer si un service fournit un paginateur pour une API particulière consiste à examiner la définition d'une classe de client de service dans la référence de l'AWS SDK pour .NET API.

Par exemple, si vous examinez la définition de la AmazonCloudWatchLogsClient classe, vous voyez une Paginators propriété. Il s'agit de la propriété qui fournit un paginateur pour Amazon CloudWatch Logs.

Que m'apportent les paginateurs ?

Les paginateurs contiennent des propriétés qui vous permettent de voir les réponses complètes. Ils contiennent également généralement une ou plusieurs propriétés qui vous permettent d'accéder aux parties les plus intéressantes des réponses, que nous appellerons les résultats clés.

Par exemple, dans ce qui AmazonCloudWatchLogsClient précède, l'Paginatorobjet contient une Responses propriété avec l'DescribeLogGroupsResponseobjet complet issu de l'appel d'API. Cette Responses propriété contient, entre autres, une collection de groupes de journaux.

L'objet Paginator contient également un résultat clé nommé. LogGroups Cette propriété contient uniquement la partie de la réponse relative aux groupes de journaux. L'obtention de ce résultat clé vous permet de réduire et de simplifier votre code dans de nombreuses circonstances.

Pagination synchrone ou asynchrone

Les paginateurs fournissent des mécanismes de pagination synchrones et asynchrones. La pagination synchrone est disponible dans les projets .NET Framework 4.7.2 (ou version ultérieure). La pagination asynchrone est disponible dans les projets .NET Core (.NET Core 3.1, .NET 5, etc.).

Les opérations asynchrones et .NET Core étant recommandés, l'exemple suivant vous montre la pagination asynchrone. Des informations sur la façon d'effectuer les mêmes tâches à l'aide de la pagination synchrone et de .NET Framework 4.7.2 (ou version ultérieure) sont affichées à la suite de l'exemple présenté dans. Considérations supplémentaires pour les paginateurs

Exemple

L'exemple suivant vous montre comment utiliser le AWS SDK pour .NET pour afficher une liste de groupes de journaux. En revanche, l'exemple montre comment procéder à la fois avec et sans paginateurs. Avant de regarder le code complet, affiché plus loin, considérez les extraits suivants.

Obtenir des groupes de CloudWatch journaux sans paginateurs

      // Loop as many times as needed to get all the log groups
      var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit};
      do
      {
        Console.WriteLine($"Getting up to {LogGroupLimit} log groups...");
        var response = await cwClient.DescribeLogGroupsAsync(request);
        foreach(var logGroup in response.LogGroups)
        {
          Console.WriteLine($"{logGroup.LogGroupName}");
        }
        request.NextToken = response.NextToken;
      } while(!string.IsNullOrEmpty(request.NextToken));

Obtenir des groupes de CloudWatch journaux à l'aide de paginateurs

      // No need to loop to get all the log groups--the SDK does it for us behind the scenes
      var paginatorForLogGroups =
        cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest());
      await foreach(var logGroup in paginatorForLogGroups.LogGroups)
      {
        Console.WriteLine(logGroup.LogGroupName);
      }

Les résultats de ces deux extraits sont exactement les mêmes, de sorte que l'avantage d'utiliser des paginateurs est clairement visible.

Code complet

Cette section présente les références pertinentes et le code complet de cet exemple.

using System;
using System.Threading.Tasks;
using Amazon.CloudWatchLogs;
using Amazon.CloudWatchLogs.Model;

namespace CWGetLogGroups
{
  class Program
  {
    // A small limit for demonstration purposes
    private const int LogGroupLimit = 3;

    //
    // Main method
    static async Task Main(string[] args)
    {
      var cwClient = new AmazonCloudWatchLogsClient();
      await DisplayLogGroupsWithoutPaginators(cwClient);
      await DisplayLogGroupsWithPaginators(cwClient);
    }


    //
    // Method to get CloudWatch log groups without paginators
    private static async Task DisplayLogGroupsWithoutPaginators(IAmazonCloudWatchLogs cwClient)
    {
      Console.WriteLine("\nGetting list of CloudWatch log groups without using paginators...");
      Console.WriteLine("------------------------------------------------------------------");

      // Loop as many times as needed to get all the log groups
      var request = new DescribeLogGroupsRequest{Limit = LogGroupLimit};
      do
      {
        Console.WriteLine($"Getting up to {LogGroupLimit} log groups...");
        DescribeLogGroupsResponse response = await cwClient.DescribeLogGroupsAsync(request);
        foreach(LogGroup logGroup in response.LogGroups)
        {
          Console.WriteLine($"{logGroup.LogGroupName}");
        }
        request.NextToken = response.NextToken;
      } while(!string.IsNullOrEmpty(request.NextToken));
    }


    //
    // Method to get CloudWatch log groups by using paginators
    private static async Task DisplayLogGroupsWithPaginators(IAmazonCloudWatchLogs cwClient)
    {
      Console.WriteLine("\nGetting list of CloudWatch log groups by using paginators...");
      Console.WriteLine("-------------------------------------------------------------");

      // Access the key results; i.e., the log groups
      // No need to loop to get all the log groups--the SDK does it for us behind the scenes
      Console.WriteLine("\nFrom the key results...");
      Console.WriteLine("------------------------");
      IDescribeLogGroupsPaginator paginatorForLogGroups =
        cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest());
      await foreach(LogGroup logGroup in paginatorForLogGroups.LogGroups)
      {
        Console.WriteLine(logGroup.LogGroupName);
      }

      // Access the full response
      // Create a new paginator, do NOT reuse the one from above
      Console.WriteLine("\nFrom the full response...");
      Console.WriteLine("--------------------------");
      IDescribeLogGroupsPaginator paginatorForResponses =
        cwClient.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest());
      await foreach(DescribeLogGroupsResponse response in paginatorForResponses.Responses)
      {
        Console.WriteLine($"Content length: {response.ContentLength}");
        Console.WriteLine($"HTTP result: {response.HttpStatusCode}");
        Console.WriteLine($"Metadata: {response.ResponseMetadata}");
        Console.WriteLine("Log groups:");
        foreach(LogGroup logGroup in response.LogGroups) 
        {
          Console.WriteLine($"\t{logGroup.LogGroupName}");
        }
      }
    }
  }
}

Considérations supplémentaires pour les paginateurs