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

このドキュメントは、 のバージョン 1 AWS CLI のみを対象としています。のバージョン 2 に関連するドキュメントについては AWS CLI、「 バージョン 2 ユーザーガイド」を参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

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

サーバー側のページ分割

項目の大きなリストを返すことができるコマンドの場合、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 のページ分割と基本のサービスを同期させます。リスト全体を取得し、必要な解析オペレーションをローカルで実行することもできます。