在 中使用分頁結果 AWS SDK for .NET - AWS SDK for .NET (V4)
在哪裡可以找到分頁程式？分頁程式提供什麼？同步與非同步分頁範例分頁程式的其他考量事項

第 4 版 (V4) AWS SDK for .NET 已發行！

如需有關中斷變更和遷移應用程式的資訊，請參閱遷移主題。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 中使用分頁結果 AWS SDK for .NET

有些 AWS 服務會收集和存放大量資料，您可以使用 的 API 呼叫來擷取這些資料 AWS SDK for .NET。如果您想要擷取的資料量對於單一 API 呼叫變得太大，您可以透過使用分頁將結果分成更易於管理的部分。

為了讓您能夠執行分頁，軟體開發套件中許多服務用戶端的請求和回應物件會提供接續字符 （通常名為 NextToken)。其中一些服務用戶端也提供分頁程式。

分頁程式可讓您避免接續字符的額外負荷，這可能涉及迴圈、狀態變數、多個 API 呼叫等。當您使用分頁程式時，您可以透過迴圈foreach的宣告單行程式碼，從 AWS 服務擷取資料。如果需要多個 API 呼叫來擷取資料，分頁器會為您處理。

在哪裡可以找到分頁程式？

並非所有 服務都提供分頁程式。判斷服務是否為特定 API 提供分頁器的一種方法是查看 AWS SDK for .NET API 參考中服務用戶端類別的定義。

例如，如果您檢查 AmazonCloudWatchLogsClient 類別的定義，您會看到 Paginators 屬性。這是為 Amazon CloudWatch Logs 提供分頁器的 屬性。

分頁程式提供什麼？

分頁程式包含可讓您查看完整回應的屬性。它們通常也包含一或多個屬性，可讓您存取最有趣的回應部分，我們將呼叫關鍵結果。

例如，在先前AmazonCloudWatchLogsClient提到的 中， Paginator 物件包含具有 API 呼叫中完整 DescribeLogGroupsResponse 物件的 Responses 屬性。此Responses屬性包含日誌群組的集合。

Paginator 物件也包含一個名為 的金鑰結果LogGroups。此屬性只會保留回應的日誌群組部分。擁有此金鑰結果可讓您在許多情況下減少和簡化程式碼。

同步與非同步分頁

分頁程式提供同步和非同步的分頁機制。同步分頁可在 .NET Framework 4.7.2 （或更新版本） 專案中使用。.NET Core 專案 (.NET Core 3.1、.NET 5 等） 提供非同步分頁。

由於建議使用非同步操作和 .NET Core，接下來的範例會顯示非同步分頁。有關如何使用同步分頁和 .NET Framework 4.7.2 （或更新版本） 執行相同任務的資訊會顯示在 中的範例之後。 分頁程式的其他考量事項

範例

下列範例說明如何使用 AWS SDK for .NET 來顯示日誌群組的清單。反之，此範例示範如何使用和不使用分頁程式來執行此操作。在查看稍後顯示的完整程式碼之前，請考慮下列程式碼片段。

在沒有分頁器的情況下取得 CloudWatch 日誌群組

      // 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 日誌群組

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

這兩個程式碼片段的結果完全相同，因此使用分頁器的優勢可以清楚地看到。

注意

在您嘗試建置並執行完整程式碼之前，請確定您已設定環境和專案。

您可能還需要 Microsoft.Bcl.AsyncInterfaces NuGet 套件，因為非同步分頁程式使用 IAsyncEnumerable 介面。

完成程式碼

本節顯示此範例的相關參考和完整程式碼。

NuGet 套件：

程式設計元素：

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

分頁程式的其他考量事項

  • 分頁程式無法多次使用

    如果您需要程式碼中多個位置的特定 AWS 分頁器結果，則不得多次使用分頁器物件。反之，請在每次需要時建立新的分頁器。此概念顯示在 DisplayLogGroupsWithPaginators方法中的上述範例程式碼中。

  • 同步分頁

    同步分頁適用於 .NET Framework 4.7.2 （或更新版本） 專案。

    若要查看，請建立 .NET Framework 4.7.2 （或更新版本） 專案，並將上述程式碼複製到其中。然後，只需從兩個foreach分頁器呼叫中移除await關鍵字，如下列範例所示。

    /*await*/ foreach(var logGroup in paginatorForLogGroups.LogGroups)
{
  Console.WriteLine(logGroup.LogGroupName);
}

    建置並執行專案，以查看與非同步分頁相同的結果。