Verwenden paginierter Ergebnisse in der AWS SDK für .NET

Einige AWS Dienste sammeln und speichern eine große Datenmenge, die Sie mithilfe der API-Aufrufe von abrufen können. AWS SDK für .NET Wenn die Datenmenge, die Sie abrufen möchten, für einen einzelnen API-Aufruf zu groß wird, können Sie die Ergebnisse mithilfe der Paginierung in überschaubarere Teile aufteilen.

Damit Sie die Paginierung durchführen können, stellen die Anforderungs- und Antwortobjekte vieler Service-Clients im SDK ein Fortführungstoken (in der Regel benannt) bereit. NextToken Einige dieser Service-Clients bieten auch Paginatoren an.

Paginatoren ermöglichen es Ihnen, den Overhead des Continuation-Tokens zu vermeiden, der Schleifen, Zustandsvariablen, mehrere API-Aufrufe usw. beinhalten kann. Wenn Sie einen Paginator verwenden, können Sie Daten von einem AWS Dienst mithilfe einer einzigen Codezeile, der Deklaration einer Schleife, abrufen. foreach Wenn mehrere API-Aufrufe erforderlich sind, um die Daten abzurufen, erledigt der Paginator dies für Sie.

Wo finde ich Paginatoren?

Nicht alle Dienste bieten Paginatoren an. Eine Möglichkeit, festzustellen, ob ein Dienst einen Paginator für eine bestimmte API bereitstellt, besteht darin, sich die Definition einer Service-Client-Klasse in der API-Referenz anzusehen. AWS SDK für .NET

Wenn Sie beispielsweise die Definition für die AmazonCloudWatchLogsClient Klasse untersuchen, sehen Sie eine Paginators Eigenschaft. Dies ist die Eigenschaft, die einen Paginator für Amazon CloudWatch Logs bereitstellt.

Was geben mir Paginatoren?

Paginatoren enthalten Eigenschaften, die es Ihnen ermöglichen, vollständige Antworten zu sehen. Sie enthalten in der Regel auch eine oder mehrere Eigenschaften, die es Ihnen ermöglichen, auf die interessantesten Teile der Antworten zuzugreifen, die wir als die wichtigsten Ergebnisse bezeichnen.

In dem zuvor AmazonCloudWatchLogsClient genannten Beispiel enthält das Paginator Objekt beispielsweise eine Responses Eigenschaft mit dem vollständigen DescribeLogGroupsResponse Objekt aus dem API-Aufruf. Diese Responses Eigenschaft enthält unter anderem eine Sammlung der Protokollgruppen.

Das Paginator-Objekt enthält auch ein Schlüsselergebnis mit dem Namen. LogGroups Diese Eigenschaft enthält nur den Teil der Protokollgruppen der Antwort. Mit diesem wichtigen Ergebnis können Sie Ihren Code unter vielen Umständen reduzieren und vereinfachen.

Synchrone oder asynchrone Paginierung

Paginatoren bieten sowohl synchrone als auch asynchrone Mechanismen für die Paginierung. Synchrone Paginierung ist in Projekten von.NET Framework 4.7.2 (oder höher) verfügbar. Asynchrone Paginierung ist in .NET Core-Projekten (.NET Core 3.1, .NET 5 usw.) verfügbar.

Da asynchrone Operationen und .NET Core empfohlen werden, zeigt Ihnen das nächste Beispiel die asynchrone Paginierung. Informationen darüber, wie dieselben Aufgaben mit synchroner Paginierung und .NET Framework 4.7.2 (oder höher) ausgeführt werden, finden Sie nach dem Beispiel in. Zusätzliche Überlegungen für Paginatoren

Beispiel

Das folgende Beispiel zeigt, wie Sie das verwenden, AWS SDK für .NET um eine Liste von Protokollgruppen anzuzeigen. Im Gegensatz dazu zeigt das Beispiel, wie Sie dies sowohl mit als auch ohne Paginatoren tun können. Bevor Sie sich den vollständigen Code ansehen, der später gezeigt wird, sollten Sie sich die folgenden Codefragmente ansehen.

CloudWatch Loggruppen ohne Paginatoren abrufen

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

CloudWatch Loggruppen mithilfe von Paginatoren abrufen

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

Die Ergebnisse dieser beiden Snippets sind exakt identisch, sodass der Vorteil der Verwendung von Paginatoren deutlich sichtbar ist.

Vollständiger Code

Dieser Abschnitt enthält relevante Referenzen und den vollständigen Code für dieses Beispiel.

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

Zusätzliche Überlegungen für Paginatoren