Paginadores

Alguns AWS serviços coletam e armazenam uma grande quantidade de dados, que você pode recuperar usando as API chamadas do AWS SDK for .NET. Se a quantidade de dados que você deseja recuperar se tornar muito grande para uma única API chamada, você pode dividir os resultados em partes mais gerenciáveis por meio do uso da paginação.

Para permitir que você realize a paginação, os objetos de solicitação e resposta de muitos clientes de serviço SDK fornecem um token de continuação (normalmente chamado). NextToken Alguns desses clientes de serviço também fornecem paginadores.

Os paginadores permitem que você evite a sobrecarga do token de continuação, que pode envolver loops, variáveis de estado, várias API chamadas e assim por diante. Ao usar um paginador, você pode recuperar dados de um serviço da AWS através de uma única linha de código, a declaração de um loop foreach. Se forem necessárias várias API chamadas para recuperar os dados, o paginador cuidará disso para você.

Onde posso encontrar paginadores?

Nem todos os serviços oferecem paginadores. Uma forma de determinar se um serviço fornece um paginador para um determinado API é examinar a definição de uma classe de cliente de serviço na AWS SDK for .NET API Referência.

Por exemplo, se você examinar a definição da AmazonCloudWatchLogsClientclasse, verá uma Paginators propriedade. Essa é a propriedade que fornece um paginador para o Amazon CloudWatch Logs.

O que os paginadores me oferecem?

Os paginadores contêm propriedades que permitem que você veja as respostas completas. Eles também costumam conter uma ou mais propriedades que permitem acessar as partes mais interessantes das respostas, que chamaremos de resultados-chave.

Por exemplo, no AmazonCloudWatchLogsClient mencionado anteriormente, o Paginator objeto contém uma Responses propriedade com o DescribeLogGroupsResponseobjeto completo da API chamada. Essa propriedade Responses contém, entre outras coisas, uma coleção dos grupos de logs.

O objeto Paginator também contém um resultado chave chamado LogGroups. Essa propriedade contém apenas a parte da resposta dos grupos de logs. Ter esse resultados-chaves permite que você reduza e simplifique seu código em muitas circunstâncias.

Paginação síncrona em comparação à assíncrona

Os paginadores fornecem mecanismos síncronos e assíncronos para paginação. A paginação síncrona está disponível em. NETProjetos do Framework 4.7.2 (ou posterior). A paginação assíncrona está disponível em. NETProjetos principais (. NETNúcleo 3.1,. NET5 e assim por diante).

Porque operações assíncronas e. NETOs principais são recomendados. O exemplo a seguir mostra a paginação assíncrona. Informações sobre como realizar as mesmas tarefas usando paginação síncrona e. NETO Framework 4.7.2 (ou posterior) é mostrado após o exemplo em. Considerações adicionais sobre paginadores

Exemplo

O exemplo a seguir mostra como usar o AWS SDK for .NET para exibir uma lista de grupos de registros. Para fins de comparação, o exemplo mostra como fazer isso com e sem paginadores. Antes de examinar o código completo, mostrado posteriormente, considere os trechos a seguir.

Obtendo grupos CloudWatch de registros sem paginadores

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

Obtendo grupos de CloudWatch registros usando paginadores

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

Os resultados desses dois trechos são exatamente os mesmos, então a vantagem de usar paginadores pode ser vista claramente.

Código completo

Esta seção mostra as referências relevantes e o código completo desse exemplo.

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

Considerações adicionais sobre paginadores