Utilizzo dei risultati impaginati nel AWS SDK per .NET

Alcuni AWS servizi raccolgono e archiviano una grande quantità di dati, che è possibile recuperare utilizzando le chiamate API di. AWS SDK per .NET Se la quantità di dati che desideri recuperare diventa troppo grande per una singola chiamata API, puoi suddividere i risultati in parti più gestibili tramite l'uso della paginazione.

Per consentire l'impaginazione, gli oggetti di richiesta e risposta per molti client di servizio nell'SDK forniscono un token di continuazione (in genere denominato). NextToken Alcuni di questi client di servizio forniscono anche impaginatori.

Gli impaginatori consentono di evitare il sovraccarico del token di continuazione, che potrebbe comportare loop, variabili di stato, più chiamate API e così via. Quando si utilizza un paginatore, è possibile recuperare i dati da un AWS servizio tramite una singola riga di codice, una dichiarazione di loop. foreach Se sono necessarie più chiamate API per recuperare i dati, l'impaginatore lo gestisce per te.

Dove posso trovare gli impaginatori?

Non tutti i servizi forniscono paginatori. Un modo per determinare se un servizio fornisce un paginatore per una particolare API è esaminare la definizione di una classe client di servizio nell'API Reference. AWS SDK per .NET

Ad esempio, se si esamina la definizione della AmazonCloudWatchLogsClient classe, viene visualizzata una Paginators proprietà. Questa è la proprietà che fornisce un paginatore per Amazon CloudWatch Logs.

Cosa mi offrono gli impaginatori?

Gli impaginatori contengono proprietà che consentono di visualizzare le risposte complete. In genere contengono anche una o più proprietà che consentono di accedere alle parti più interessanti delle risposte, che chiameremo risultati chiave.

Ad esempio, in quanto AmazonCloudWatchLogsClient menzionato in precedenza, l'Paginatoroggetto contiene una Responses proprietà con l'DescribeLogGroupsResponseoggetto completo della chiamata API. Questa Responses proprietà contiene, tra le altre cose, una raccolta dei gruppi di log.

L'oggetto Paginator contiene anche un risultato chiave denominato. LogGroups Questa proprietà contiene solo la parte della risposta relativa ai gruppi di log. Avere questo risultato chiave consente di ridurre e semplificare il codice in molte circostanze.

Impaginazione sincrona e asincrona

Gli impaginatori forniscono meccanismi sincroni e asincroni per l'impaginazione. L'impaginazione sincrona è disponibile nei progetti .NET Framework 4.7.2 (o versioni successive). L'impaginazione asincrona è disponibile nei progetti .NET Core (.NET Core 3.1, .NET 5 e così via).

Poiché le operazioni asincrone e .NET Core sono consigliate, l'esempio che segue mostra l'impaginazione asincrona. Le informazioni su come eseguire le stesse attività utilizzando l'impaginazione sincrona e .NET Framework 4.7.2 (o versioni successive) sono mostrate dopo l'esempio in. Considerazioni aggiuntive per gli impaginatori

Esempio

L'esempio seguente mostra come utilizzare il per visualizzare un elenco AWS SDK per .NET di gruppi di log. Per contrasto, l'esempio mostra come eseguire questa operazione con e senza impaginatori. Prima di esaminare il codice completo, mostrato più avanti, considera i seguenti frammenti.

Ottenere gruppi di CloudWatch log senza impaginatori

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

Ottenere gruppi di CloudWatch log utilizzando gli impaginatori

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

I risultati di questi due frammenti sono esattamente gli stessi, quindi il vantaggio derivante dall'uso degli impaginatori è evidente.

Codice completo

Questa sezione mostra i riferimenti pertinenti e il codice completo per questo esempio.

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

Considerazioni aggiuntive per gli impaginatori