Paginadores

Algunos AWS servicios recopilan y almacenan una gran cantidad de datos, que puede recuperar mediante las API llamadas del. AWS SDK for .NET Si la cantidad de datos que desea recuperar es demasiado grande para una sola API llamada, puede dividir los resultados en partes más manejables mediante el uso de la paginación.

Para poder realizar la paginación, los objetos de solicitud y respuesta de muchos clientes del servicio que contienen SDK proporcionan un token de continuación (normalmente denominado). NextToken Algunos de estos clientes de servicio también proporcionan paginadores.

Los paginadores permiten evitar la sobrecarga del token de continuación, que puede implicar bucles, variables de estado, API llamadas múltiples, etc. Cuando se utiliza un paginador, se pueden recuperar datos de un servicio de AWS con una sola línea de código, mediante la declaración de un bucle foreach. Si se necesitan varias API llamadas para recuperar los datos, el paginador se encarga de ello por ti.

¿Dónde puedo encontrar paginadores?

No todos los servicios ofrecen paginadores. Una forma de determinar si un servicio proporciona un paginador para un determinado servicio API es observar la definición de una clase de cliente de servicio en la Referencia.AWS SDK for .NET API

Por ejemplo, si examina la definición de la AmazonCloudWatchLogsClientclase, verá una Paginators propiedad. Esta es la propiedad que proporciona un paginador para Amazon CloudWatch Logs.

¿Qué me proporcionan los paginadores?

Los paginadores contienen propiedades que permiten ver respuestas completas. También suelen contener una o más propiedades que permiten acceder a las partes más interesantes de las respuestas, que denominaremos resultados clave.

Por ejemplo, en lo AmazonCloudWatchLogsClient mencionado anteriormente, el Paginator objeto contiene una Responses propiedad con el DescribeLogGroupsResponseobjeto completo de la API llamada. Esta propiedad Responses contiene, entre otras cosas, una colección de los grupos de registros.

El objeto Paginator contiene también un resultado clave denominado LogGroups. Esta propiedad contiene solo la parte de grupos de registros de la respuesta. Tener este resultado clave permite reducir y simplificar el código en muchas ocasiones.

Paginación sincrónica frente a paginación asincrónica

Los paginadores proporcionan mecanismos de paginación sincrónicos y asincrónicos. La paginación sincrónica está disponible en. NETProyectos de Framework 4.7.2 (o versiones posteriores). La paginación asíncrona está disponible en. NETProyectos principales (. NETNúcleo 3.1,. NET5, y así sucesivamente).

Porque las operaciones asíncronas y. NETSe recomiendan los núcleos, el ejemplo que viene a continuación muestra la paginación asíncrona. Información sobre cómo realizar las mismas tareas mediante la paginación sincrónica y. NETEl marco 4.7.2 (o posterior) se muestra después del ejemplo en. Consideraciones adicionales sobre los paginadores

Ejemplo

En el siguiente ejemplo, se muestra cómo utilizar el AWS SDK for .NET para mostrar una lista de grupos de registros. Para mostrar las diferencias, en el ejemplo se muestra cómo hacerlo con y sin paginadores. Antes de echar un vistazo al código completo, que se muestra más adelante, analice los siguientes fragmentos de código.

Obtener grupos de CloudWatch registros sin 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));

Obtener grupos de CloudWatch registros mediante 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);
      }

Los resultados de estos dos fragmentos de código son exactamente iguales, por lo que se ve claramente la ventaja de utilizar paginadores.

Código completo

En esta sección se muestran las referencias relevantes y el código completo de este ejemplo.

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

Consideraciones adicionales sobre los paginadores