本文件僅適用於第 1 AWS CLI 版。如需與版本 2 的相關文件 AWS CLI，請參閱第 2 版使用者指南。

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

使用 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 參數

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

$ 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 和基礎服務的分頁。您亦可擷取整個清單，並於本機執行所需的分頁操作。