分頁程式 - AWS SDK for .NET
我在哪裡可以找到分頁器？分頁器給我什麼？同步與異步分頁範例分頁器的其他考量

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

分頁程式

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

為了使您能夠執行分頁，SDK 中許多服務客戶端的請求和響應對象提供了一個延續令牌（通常名為NextToken）。其中一些服務客戶端還提供分頁器。

分頁器使您能夠避免延續令牌的開銷，這可能涉及循環，狀態變量，多個 API 調用等。當您使用分頁器時，您可以通過一行代碼（foreach循環的聲明）從AWS服務中檢索數據。如果需要多個 API 調用來檢索數據，分頁器會為您處理此問題。

我在哪裡可以找到分頁器？

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

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

分頁器給我什麼？

分頁器包含可讓您查看完整回應的屬性。它們通常還包含一個或多個屬性，可讓您訪問響應中最有趣的部分，我們將其稱為關鍵結果。

例如，在前AmazonCloudWatchLogsClient面提到的，Paginator對象包含一個Responses屬性，其中包含來自 API 調用的完整DescribeLogGroupsResponse對象。除其他外，此內Responses容還包含記錄群組的集合。

分頁器對象還包含一個名為的關鍵結果。LogGroups此屬性只會保留回應的記錄群組部分。有了這個關鍵結果，您可以在許多情況下減少和簡化您的代碼。

同步與異步分頁

分頁器提供了用於分頁同步和異步機制。同步分頁可在 .NET 框架 4.5（或更高版本）項目中使用。非同步分頁可用於 .NET 核心專案 (.NET 核心 3.1、.NET 5 等等)。

因為建議使用非同步作業和 .NET Core，因此接下來的範例會顯示非同步分頁。在中的範例之後會顯示有關如何使用同步分頁和 .NET Framework 4.5 (或更新版本) 執行相同工作的資訊分頁器的其他考量。

範例

下列範例說明如何使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);
      }

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

注意

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

您可能還需要微軟 .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分頁器的結果，則不得多次使用 paginator 物件。而是在每次需要時創建一個新的分頁器。這個概念顯示在DisplayLogGroupsWithPaginators方法的前面的示例代碼中。

  • 同步分頁

    同步分頁可用於 .NET 框架 4.5（或更高版本）的項目。

    警告

    從 2024 年 8 月 15 日起，AWS SDK for .NET將終止對 .NET 框架 3.5 的支持，並將最低 .NET 框架版本更改為 4.6.2。如需詳細資訊，請參閱部落格文章 .NET 架構 3.5 和 4.5 目標的重要變更AWS SDK for .NET。

    要看到這一點，創建一個 .NET Framework 4.5（或更高版本）項目，並將前面的代碼複製到它。然後，只要從兩個 foreach paginator 呼叫中移除await關鍵字，如下列範例所示。

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

    建置並執行專案，以查看您使用非同步分頁所看到的相同結果。