Using the pagination options in the AWS CLI
このトピックでは、AWS Command Line Interface (AWS CLI) からの出力をページネーションするためのさまざまな方法を示します。
AWS CLI からページネーションを制御する方法は主に 2 つあります。
サーバー側のページ分割パラメータが最初に処理され、出力がクライアント側のページ分割に送信されます。
サーバー側のページ分割
項目の大きなリストを返すほとんどのコマンドの場合、AWS CLI がサービスの API を呼び出してリストを生成するときに出力に含める項目の数を制御するための複数のオプションが AWS CLI にあります。AWS CLI のサーバー側ページ分割は AWS のサービス API によって有効になるため、これらのオプションはサービス API が有効にしている場合にのみ機能します。
AWS CLI コマンドには、以下のオプションがあります。
デフォルトでは、AWS CLI は、個々のサービスによって決定されるページサイズを使用し、利用可能なすべての項目を取得します。例えば、Amazon S3 では、デフォルトのページサイズは 1,000 です。3,500 のオブジェクトを含む Amazon S3 バケットで aws
s3api list-objects
を実行すると、AWS CLI は Simple Storage Service (Amazon S3) に対して 4 つの呼び出しを自動的に実行し、サービス固有の分割ロジックをバックグラウンドで処理して、最終的な出力で 3,500 オブジェクトのすべてを返します。
特定のコマンドがサーバー側ページ分割に対応しているかどうかについては、またはAWS CLI バージョン 2 リファレンスガイド
--no-paginate パラメータの使用方法
--no-paginate
オプションでは、クライアント側で分割トークンの追従を無効にします。コマンドを使用する場合、デフォルトでは、AWS CLI は複数の呼び出しを自動的に行い、すべての可能な結果を返してページ分割を作成します。ページごとに 1 回の呼び出し。ページ分割を無効にすると、コマンド結果の最初のページに対して AWS CLI は 1 回の呼び出しのみを行います。
例えば、3,500 のオブジェクトを含む Amazon S3 バケットで aws s3api list-objects
を実行する場合、AWS CLI は Amazon S3 への最初の呼び出しのみを行い、最終的な出力では最初の 1,000 のオブジェクトのみを返します。
$
aws s3api list-objects \ --bucket amzn-s3-demo-bucket \
--no-paginate
{ "Contents": [ ...
--page-size パラメータの使用方法
大量のリソースに対してリストコマンドを実行しているときに問題が発生する場合は、デフォルトのページサイズが大きすぎる可能性があります。これにより、AWS サービスの呼び出しが最大許容時間を超えて、「タイムアウト」エラーを生成することがあります。--page-size
オプションを使用して、AWS CLI が AWS のサービスの 1 回の呼び出しで要求する項目数を少なくすることができます。その場合でも AWS CLI は完全なリストを取得しますが、多数のサービス API コールをバックグラウンドで実行し、1 回の呼び出しで取得する項目数が少なくなります。このため、個々の呼び出しがタイムアウトにならずに成功する可能性が高くなります。ページサイズを変更しても、出力には影響しません。出力を生成するために必要な API 呼び出しの数が変わるだけです。
$
aws s3api list-objects \ --bucket amzn-s3-demo-bucket \
--page-size 100
{ "Contents": [ ...
--max-items パラメータの使用方法
AWS CLI 出力で一度に含める項目を少なくするには、--max-items
オプションを使用します。前に説明したように、AWS CLI はサービスとのページ区切りを処理しますが、指定した時点での項目数のみを出力します。
$
aws s3api list-objects \ --bucket amzn-s3-demo-bucket \ --max-items 100
{ "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==", "Contents": [ ...
--starting-token パラメータの使用方法
出力される項目数 (--max-items
) が基本の API 呼び出しによって返される合計項目数より少ない場合、出力には NextToken
が含まれ、これにより、後続のコマンドを渡して、次の項目のセットを取得できます。次の例は、前の例で返された NextToken
値を使用して、2 番目の 100 項目を取得する方法を示しています。
注記
パラメータ --starting-token
を null または空にすることはできません。前のコマンドが NextToken
値を返さない場合、返す項目はこれ以上存在せず、このコマンドを再度呼び出す必要はありません。
$
aws s3api list-objects \ --bucket amzn-s3-demo-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
コマンドラインオプションを使用して 1 回のコマンド使用のページャーを無効にする。 -
cli_pager
設定またはAWS_PAGER
変数を空の文字列に設定する。
クライアント側のページャーのトピック:
cli_pager 設定の使用方法
頻繁に利用される構成設定および認証情報を AWS CLI が維持するファイルに保存することができます。名前プロファイルの設定は、default
プロファイルの設定よりも優先されます。構成設定の詳細については、「Configuration and credential file settings in the AWS CLI」を参照してください。
次の例では、デフォルトの出力ページャーを less
プログラムに設定します。
[default] cli_pager=less
以下の例では、ページャーの使用を無効にするようにデフォルトを設定します。
[default] cli_pager=
AWS_PAGER 環境変数の設定方法
次の例では、デフォルトの出力ページャーを less
プログラムに設定します。環境変数の詳細については、「Configuring environment variables for the AWS CLI」を参照してください。
--no-cli-pager オプションの使用方法
1 つのコマンドでのページャーの使用を無効にするには、--no-cli-pager
オプションを使用します。コマンドラインオプションの詳細については、「AWS CLI のコマンドラインオプション」を参照してください。
$
aws s3api list-objects \ --bucket amzn-s3-demo-bucket \
--no-cli-pager
{ "Contents": [ ...
ページャーフラグの使用方法
ページ分割プログラムで自動的に使用するフラグを指定できます。フラグは、使用するページ分割プログラムによって異なります。次に示すのは、less
および more
の一般的なデフォルトの例です。