AWS CLI のページ分割オプションを使用する - AWS Command Line Interface

AWS CLI のページ分割オプションを使用する

このトピックでは、AWS CLI からの出力をページネーションするためのさまざまな方法を示します。

AWS CLI からページネーションを制御する方法は主に 2 つあります。

サーバー側のページ分割パラメータが最初に処理され、出力がクライアント側のページ分割に送信されます。

サーバー側のページ分割

項目の大きなリストを返すことができるコマンドの場合、AWS Command Line Interface (AWS CLI) がサービスの 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 オブジェクトのすべてを返します。

--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 my-bucket \ --no-paginate { "Contents": [ ...

--page-size パラメータの使用方法

大量のリソースに対してリストコマンドを実行しているときに問題が発生する場合は、デフォルトのページサイズが大きすぎる可能性があります。これにより、AWS サービスの呼び出しが最大許容時間を超えて、「タイムアウト」エラーを生成することがあります。--page-size オプションを使用して、AWS CLI が AWS のサービスの 1 回の呼び出しで要求する項目数を少なくすることができます。その場合でも AWS CLI は完全なリストを取得しますが、多数のサービス API コールをバックグラウンドで実行し、1 回の呼び出しで取得する項目数が少なくなります。このため、個々の呼び出しがタイムアウトにならずに成功する可能性が高くなります。ページサイズを変更しても、出力には影響しません。出力を生成するために必要な 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 値を使用して、2 番目の 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 コマンドラインオプションを使用して 1 回のコマンド使用のページャーを無効にする。

  • 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 オプションの使用方法

1 つのコマンドでのページャーの使用を無効にするには、--no-cli-pager オプションを使用します。コマンドラインオプションの詳細については、「コマンドラインオプション」を参照してください。

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

ページャーフラグの使用方法

ページ分割プログラムで自動的に使用するフラグを指定できます。フラグは、使用するページ分割プログラムによって異なります。次に示すのは、less および more の一般的なデフォルトの例です。

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 フラグの詳細については、mandpages.org の「less」を参照してください。

Windows

特に指定しない場合、AWS CLI バージョン 2 がデフォルトで使用するページャーは more で、追加のフラグはありません。

次の例では、/c パラメータを使用しています

C:\> setx AWS_PAGER "more /c"

more フラグの詳細については、Microsoft Docs の「more」を参照してください。