使用 AWS CLI 分頁選項 - AWS Command Line Interface

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

使用 AWS CLI 分頁選項

本主題說明對 AWS CLI 輸出進行分頁的不同方法。

主要有兩種方法來控制 AWS CLI 輸出的分頁。

伺服器端分頁參數先處理,然後所有輸出都傳送到用戶端分頁。

伺服器端分頁

對於會傳回大型項目清單的命令,AWS Command Line Interface (AWS CLI) 新增多個選項來控制當 AWS CLI 呼叫服務 API 以填入清單時,輸出中包含的項目數。

在預設情況下,AWS CLI使用由單一服務決定的頁面大小,並檢索所有可用的項目。例如,Amazon S3 的預設頁面大小為 1000。例如,如果您在包含 3,500 個物件的 Amazon S3 儲存貯體上執行 aws s3api list-objects,AWS CLI 會自動對 Amazon S3 進行 4 次呼叫、在背景為您處理服務特定的分頁邏輯,並在最終輸出中傳回全部 3,500 個物件。

如何使用 --no-paginate 參數

--no-paginate 選項在客户端停用以下分頁標記。在使用命令時,預設情況下,AWS CLI 會自動進行多個呼叫來傳回所有可能的結果,以建立分頁。每個頁面一個呼叫。停用具有 AWS CLI 的分頁,僅會呼叫命令結果第一頁一次。

例如,如果您在包含 3,500 個物件的 Amazon S3 儲存貯體上執行 aws s3api list-objects,則 AWS CLI 僅會對 Amazon S3 進行第一次呼叫,且僅傳回最終輸出中的前 1,000 個物件。

$ aws s3api list-objects \ --bucket my-bucket \ --no-paginate { "Contents": [ ...

如何使用 --page-size 參數

如果您在針對大量資源執行清單命令時發生問題,可能是預設頁面大小太高。這可能會導致呼叫 AWS 服務超過最大允許時間,並產生「逾時」錯誤。您可以使用 --page-size 選項,指定 AWS CLI 在每次呼叫 AWS 服務時請求較小的項目數。AWS CLI 仍會擷取完整清單,但會在背景中執行較大量的服務 API 呼叫,每次呼叫擷取較少的項目數。這可讓每次呼叫不逾時的成功機會更高。變更頁面大小不會影響輸出;它只會影響產生輸出所需進行的 API 呼叫數量。

$ aws s3api list-objects \ --bucket my-bucket \ --page-size 100 { "Contents": [ ...

如何使用 --max-items 參數

若要在 AWS CLI 輸出中一次擷取較少的項目,請使用 --max-items 選項。AWS CLI 仍會如先前所述搭配服務處理分頁,但一次只會列印出您指定的項目數。

$ aws s3api list-objects \ --bucket my-bucket \ --max-items 100 { "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==", "Contents": [ ...

如何使用 --starting-token 參數

如果項目輸出數量 (--max-items) 少於基礎 API 呼叫傳回的項目總數,則輸出會包含一個 NextToken,提供您在後續命令中傳送以擷取下一組項目。以下範例說明如何使用前一範例傳回的 NextToken 值,並讓您擷取第二批的 100 個項目。

注意

參數 --starting-token 不能為 null 或空白。如果先前的命令未傳回 NextToken 值,表示已沒有更多項目可傳回,您也不需要再次呼叫命令。

$ aws s3api list-objects \ --bucket my-bucket \ --max-items 100 \ --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ== { "Contents": [ ...

執行呼叫時,指定的 AWS服務可能不會每次都以相同的順序傳回項目。如果您為 --page-size--max-items 指定不同的數值,您可能會取得意外的結果,並發生遺漏或重複的項目。欲避免此情況,請對 --page-size--max-items 使用相同數字,以同步 AWS CLI 和基礎服務的分頁。您亦可擷取整個清單,並於本機執行所需的分頁操作。

用戶端分頁程式

AWS CLI 第 2 版允許使用用戶端分頁程式進行輸出。根據預設,此功能會透過作業系統的預設分頁程式傳回所有輸出。

依據優先順序,您可以使用以下方式指定輸出分頁程式:

  • 使用 default 或具名設定檔內 config 檔案中的 cli_pager 設定。

  • 使用 AWS_PAGER 環境變數。

  • 使用 PAGER 環境變數。

依優先順序,您可以透過下列方式停用所有對外部分頁程式的使用:

  • 使用 --no-cli-pager 命令列選項停用單一命令使用的分頁程式。

  • cli_pager 設定或 AWS_PAGER 變數設為空白字串。

如何使用 cli_pager 設定

您可以將常用的組態設定和憑證儲存在 AWS CLI 維護的檔案中。具名設定檔內的設定優先於 default 設定檔內的設定。如需組態設定的詳細資訊,請參閱 組態與憑證檔案設定

以下範例設定預設的輸出分頁程式至 less 程式。

[default] cli_pager=less

下列範例會將預設值設定為停用分頁程式。

[default] cli_pager=

如何使用 AWS_PAGER 環境變數

以下範例設定預設的輸出分頁程式至 less 程式。如需有關環境變數的詳細資訊,請參閱 要設定的環境變數 AWS CLI

Linux and macOS
$ export AWS_PAGER="less"
Windows
C:\> setx AWS_PAGER "less"

下列範例會停用分頁程式。

Linux and macOS
$ export AWS_PAGER=""
Windows
C:\> setx AWS_PAGER ""

如何使用 --no-cli-pager 選項

若要停用單一命令對呼叫程式的使用,請使用 --no-cli-pager 選項。如需命令列選項的詳細資訊,請參閱 命令列選項

$ aws s3api list-objects \ --bucket my-bucket \ --no-cli-pager { "Contents": [ ...

如何使用分頁程式標記

您可以指定要自動與分頁程式搭配使用的標記。標記是依您使用的分頁程式而定。以下範例是 lessmore 的典型預設內容。

Linux and macOS

如果您不另外指定,則分頁程式 AWS CLI 第 2 版會預設使用 less。如果您沒有 LESS 環境變數集,則 AWS CLI 第 2 版會使用 FRX 標記。您可以在設定 AWS CLI 分頁程式時指定標記,藉此合併標記。

下列範例使用 S 標記。然後,此標誌會與預設的 FRX 標誌合併,以建立最終 FRXS 標記。

$ export AWS_PAGER="less -S"

如果您不希望有任何 FRX 標記,可將其否定。以下範例會否定 F 標記以建立最終 RX 標記。

$ export AWS_PAGER="less -+F"

如需 less 的詳細資訊,請參閱 manpages.org 上的 less

Windows

如果您不另外指定,則分頁程式 AWS CLI 第 2 版會預設使用 more,且沒有其他標記。

下列範例會使用 /c 參數。

C:\> setx AWS_PAGER "more /c"

如需 more 的詳細資訊,請參閱 Microsoft Docs 上的more