Paginadores

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

Para permitir que você realize a paginação, os objetos de solicitação e resposta de muitos clientes de serviço no SDK fornecem um token de continuação (normalmente intitulado 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, múltiplas chamadas de API 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 múltiplas chamadas de API para recuperar os dados, o paginador lidará com isso 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 uma API específica é examinar a definição de uma classe de cliente de serviço na Referência de API do AWS SDK for .NET.

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 chamada da API. 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 projetos do.NET Framework 4.7.2 (ou posterior). A paginação assíncrona está disponível em projetos do.NET Core (.NET Core 3.1, .NET 5 e assim por diante).

Como as operações assíncronas e o .NET Core são recomendadas, o exemplo a seguir mostra a paginação assíncrona. As informações sobre como realizar as mesmas tarefas usando paginação síncrona e o.NET Framework 4.7.2 (ou posterior) são mostradas 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