# Controlling command output in the AWS CLI
このセクションでは、AWS Command Line Interface (AWS CLI) からの出力を制御するさまざまな方法を示します。ターミナルで AWS CLI 出力をカスタマイズすると、読みやすさが向上し、スクリプト自動化が合理化され、大規模なデータセットを簡単に操作できるようになります。
AWS CLI は、[`json`](cli-usage-output-format.md#json-output)、[`text`](cli-usage-output-format.md#text-output)、 [`yaml`](cli-usage-output-format.md#yaml-output)、[`off`](cli-usage-output-format.md#off-output)、および [`table`](cli-usage-output-format.md#table-output) を含む複数の[出力フォーマット](cli-usage-output-format.md)をサポートしています。一部のサービスでは、データに対してサーバー側で[ページ分割](cli-usage-pagination.md)が行われており、AWS CLI は独自のクライアント側での追加のページ分割オプション用機能を提供します。
さらに、AWS CLI は、[サーバー側およびクライアント側の両方のフィルタリング](cli-usage-filter.md)を備えており、これらを個別に、または同時に使用して、AWS CLI 出力をフィルタリングすることができます。
**Topics**
+ [機密性の高い出力](#cli-usage-output-sensitive)
+ [サーバー側の出力オプションとクライアント側の出力オプション](#cli-usage-output-server-client)
+ [Setting the output format in the AWS CLI](cli-usage-output-format.md)
+ [AWS CLI の構造化エラー出力](cli-usage-error-format.md)
+ [Using the pagination options in the AWS CLI](cli-usage-pagination.md)
+ [Filtering output in the AWS CLI](cli-usage-filter.md)
## 機密性の高い出力
AWS CLI の一部の操作により、環境変数からの情報など、機密性が高いと見なされうる情報が返される場合があります。この情報の公開は、特定のシナリオでセキュリティリスクを提示する可能性があります。例えば、情報が継続的統合と継続的デプロイ (CI/CD) ログに含まれることが考えられます。したがって、ログにこのような出力を含めるときはレビューを行い、不要な場合は出力を控えることが重要となります。
機密データの保護の詳細については、「[AWS CLI でのデータ保護](data-protection.md)」を参照してください。
以下のベストプラクティスを考慮します。
+ AWS Secrets Manager などのシークレットストアからシークレットをプログラム的に取得することを検討してください。
+ ビルドログの内容を確認して、機密情報が含まれていないことを確認します。コマンド出力を抑制するために、`/dev/null` をパイピングしたり、bash または PowerShell 変数として出力をパイプしたりキャプチャしたりするなどのアプローチを検討してください。
以下は、エラーではなく出力を `/dev/null` にリダイレクトするための bash の例です。
```
$ aws s3 ls > /dev/null
```
ターミナルの出力を抑制する方法の詳細については、使用するターミナルのユーザードキュメントを参照してください。
+ ログへのアクセスを検討し、ユースケースに応じてアクセスの範囲を適切に設定します。
## サーバー側の出力オプションとクライアント側の出力オプション
AWS CLI には、[サーバー側とクライアント側の両方のフィルタリング](cli-usage-filter.md)があり、AWS CLI 出力をフィルタリングするために個別または一緒に使用することができます。サーバー側のフィルタリングが最初に処理され、クライアント側のフィルタリングのために出力が返されます。サーバー側のフィルタリングは、サービス API によってサポートされます。クライアント側のフィルタリングは、AWS CLI パラメータを使用して `--query` クライアントによってサポートされます。
**サーバー側**の出力オプションは、AWS のサービス API で直接サポートされる機能です。フィルタリングまたはページアウトされたデータはクライアントに送信されないため、HTTP 応答時間が短縮され、より大きなデータセットの帯域幅が向上します。
**クライアント側**の出力オプションは、AWS CLI によって作成される機能です。すべてのデータはクライアントに送信され、その後、表示されるコンテンツは AWS CLI によってフィルタリングまたはページ分割されます。クライアント側のオペレーションでは、大規模なデータセットの速度や帯域幅を節約することができません。
サーバー側のオプションとクライアント側のオプションを同時に使用する場合、サーバー側のオペレーションが最初に完了し、その後クライアント側のオペレーションのためにクライアントに送信されます。これにより、サーバー側のオプションによる潜在的な速度の向上と帯域幅の節約を実現しながら、追加の AWS CLI 機能を使用して必要な出力を取得できます。
# Setting the output format in the AWS CLI
このトピックでは、AWS Command Line Interface (AWS CLI) のさまざまな出力形式について説明します。AWS CLI は以下の出力形式をサポートしています。
+ **[`json`](#json-output)** - 出力は [JSON](https://json.org/) 文字列としてフォーマットされます。
+ **[`yaml`](#yaml-output)** - 出力は [YAML](https://yaml.org/) 文字列としてフォーマットされます。
+ **[`yaml-stream`](#yaml-stream-output)** - 出力はストリームされ、[ YAML ](https://yaml.org/)文字列としてフォーマットされます。ストリーミングにより、大きなデータタイプの処理を高速化できます。
+ **[`text`](#text-output)** - 出力は、複数行のタブ区切りの文字列値としてフォーマットされます。これは、`grep`、`sed`、または `awk` などのテキストプロセッサに出力を渡すのに役立ちます。
+ **[`table`](#table-output)** - 出力は、テーブルとしてフォーマットされ、文字の「\$1\$1-」を使用してセルの境界を形成します。通常、情報は他の形式よりも読みやすい「わかりやすい」形式で表示されますが、プログラムとしては役立ちません。
+ **[`off`](#off-output)** - 出力は、stdout へのすべてのコマンド出力を制限します。これは、出力を処理せずにコマンドの終了コードを確認するだけで済む自動化スクリプトや CI/CD パイプラインに役立ちます。
## 出力形式を選択する方法
「[設定](cli-chap-configure.md)」トピックで説明したように、出力形式は 3 つの異なる方法で指定できます。
+ **`output` ファイル内の名前付きプロファイルで`config`オプションを使用する** - 次の例では、デフォルトの出力形式を `text` に設定します。
```
[default]
output=text
```
+ **`AWS_DEFAULT_OUTPUT`環境変数の使用 ** - 次の出力は、変数が変更されるか、セッションが終了するまで、このコマンドラインセッションのコマンドの形式を `table` に設定します。この環境変数を使用すると、`config` ファイルで設定された値が上書きされます。
```
$ export AWS_DEFAULT_OUTPUT="table"
```
+ ** コマンドラインで「`--output`」オプションを使用 ** - 次の例では、この 1 つのコマンドのみの出力を `json` に設定します。このコマンドでこのオプションを使用すると、現在設定されている環境変数または `config` ファイルの値をオーバーライドします。
```
$ aws swf list-domains --registration-status REGISTERED --output json
```
**重要**
指定する出力タイプによって、`--query` オプションの動作が変更されます。
`--output text` を指定する場合、出力は `--query` フィルターが適用される*前に*ページ分割され、AWS CLI は出力の*各ページ*でクエリを 1 回実行します。このため、クエリには各ページで最初に一致する要素が含まれており、予期しない余分な出力が発生する可能性があります。出力をさらにフィルタリングするには、`head` や `tail` などの他のコマンドラインツールを使用できます。
`--output json`、 `--output yaml`、`--output yaml-stream` を指定する場合、単一のネイティブな構造として完全に処理されてから `--query` フィルターが適用されます。AWS CLI は構造全体に対してクエリを 1 回だけ実行し、フィルタリングされた結果を生成してから出力されます。
## JSON 出力形式
[JSON](https://json.org) は AWS CLI のデフォルトの出力形式です。ほとんどのプログラミング言語は、組み込み関数を使用するか、公開されているライブラリを使用して、簡単に JSON 文字列をデコードできます。JSON 出力と [--query オプション](cli-usage-filter.md)を強力な方法で組み合わせて、AWS CLI JSON 形式の出力をフィルタリングおよび書式設定することができます。
`--query` ではできない可能性がある高度なフィルタリングを行うには、コマンドライン JSON プロセッサである `jq` の使用を検討してください。これをダウンロードし、公式のチュートリアルを [http://stedolan.github.io/jq/](http://stedolan.github.io/jq/) で見ることができます。
以下は、JSON 出力の例です。
```
$ aws iam list-users --output json
```
```
{
"Users": [
{
"Path": "/",
"UserName": "Admin",
"UserId": "AIDA1111111111EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/Admin",
"CreateDate": "2014-10-16T16:03:09+00:00",
"PasswordLastUsed": "2016-06-03T18:37:29+00:00"
},
{
"Path": "/backup/",
"UserName": "backup-user",
"UserId": "AIDA2222222222EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/backup/backup-user",
"CreateDate": "2019-09-17T19:30:40+00:00"
},
{
"Path": "/",
"UserName": "cli-user",
"UserId": "AIDA3333333333EXAMPLE",
"Arn": "arn:aws:iam::123456789012:user/cli-user",
"CreateDate": "2019-09-17T19:11:39+00:00"
}
]
}
```
## YAML 出力形式
[YAML](https://yaml.org) は、[YAML 形式のテンプレート](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html)をサポートする CloudFormation など、[YAML](https://yaml.org) 形式の文字列を出力または使用するサービスとツールにより、プログラムで出力を処理する場合に適しています。
`--query` ではできない可能性がある高度なフィルタリングを行うには、コマンドライン YAML プロセッサである `yq` を検討してください。*GitHub* の [yq リポジトリ](https://github.com/mikefarah/yq)から `yq` をダウンロードできます。
以下に YAML 出力例を示します。
```
$ aws iam list-users --output yaml
```
```
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## YAML ストリーム出力形式
`yaml-stream` 形式では [YAML](https://yaml.org) 形式を使用します。また、データをユーザーにストリーミングすることで、大きなデータセットの応答性を向上させ、より高速に表示できます。クエリ全体がダウンロードされる前に、YAML データの表示および使用を開始できます。
`--query` ではできない可能性がある高度なフィルタリングを行うには、コマンドライン YAML プロセッサである `yq` を検討してください。*GitHub* の [yq リポジトリ](https://github.com/mikefarah/yq)から `yq` をダウンロードできます。
`yaml-stream` 出力例を次に示します。
```
$ aws iam list-users --output yaml-stream
```
```
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
次に示す `yaml-stream` 出力例は、`--page-size` パラメータによるストリーミングされた YAML コンテンツのページ分割に関連しています。
```
$ aws iam list-users --output yaml-stream --page-size 2
```
```
- IsTruncated: true
Marker: ab1234cdef5ghi67jk8lmo9p/q012rs3t445uv6789w0x1y2z/345a6b78c9d00/1efgh234ij56klmno78pqrstu90vwxyx
Users:
- Arn: arn:aws:iam::123456789012:user/Admin
CreateDate: '2014-10-16T16:03:09+00:00'
PasswordLastUsed: '2016-06-03T18:37:29+00:00'
Path: /
UserId: AIDA1111111111EXAMPLE
UserName: Admin
- Arn: arn:aws:iam::123456789012:user/backup/backup-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /backup/
UserId: AIDA2222222222EXAMPLE
UserName: arq-45EFD6D1-CE56-459B-B39F-F9C1F78FBE19
- IsTruncated: false
Users:
- Arn: arn:aws:iam::123456789012:user/cli-user
CreateDate: '2019-09-17T19:30:40+00:00'
Path: /
UserId: AIDA3333333333EXAMPLE
UserName: cli-user
```
## テキストの出力形式
`text` 形式では、AWS CLI の出力がタブ区切りの行に整形されます。`grep`、`sed`、`awk` など、従来の Unix テキストツールでも、PowerShell スクリプトによって実行されるテキスト処理でも機能します。
`text` 出力形式は、以下に示す基本的な構造に従います。列は、基になる JSON オブジェクトの対応するキー名によってアルファベット順にソートされます。
```
IDENTIFIER sorted-column1 sorted-column2
IDENTIFIER2 sorted-column1 sorted-column2
```
`text` 出力例を次に示します。各フィールドは他のフィールドからタブで区切られ、空のフィールドがある追加のタブが含まれます。
```
$ aws iam list-users --output text
```
```
USERS arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 / AIDA1111111111EXAMPLE Admin
USERS arn:aws:iam::123456789012:user/backup/backup-user 2019-09-17T19:30:40+00:00 /backup/ AIDA2222222222EXAMPLE backup-user
USERS arn:aws:iam::123456789012:user/cli-user 2019-09-17T19:11:39+00:00 / AIDA3333333333EXAMPLE cli-user
```
4 番目の列は `PasswordLastUsed` フィールドで、最後の 2 つのエントリは空です。これらのユーザーは AWS マネジメントコンソール にサインインしないためです。
**重要**
*`text` 出力を指定する場合は、[`--query`](cli-usage-filter.md) オプションも必ず使用して、一貫した動作を確保することを強くお勧めします*。
これは、AWS サービスから返される、テキスト形式では出力列が基本の JSON オブジェクトのキー名のアルファベット順に並べられるためであり、同様のリソースが同じキー名を持つとは限らないためです。例えば、Linux ベースの Amazon EC2 インスタンスの JSON 表現は、Windows ベースのインスタンスの JSON 表現にはない要素を持つことがあり、逆も同様です。また、リソースのキー値要素が将来の更新で追加または削除されて、列の順序が変わる可能性があります。このような場合、`--query` は `text` 出力の機能を補強して、出力形式に対する完全な制御を提供します。
次の例では、コマンドは表示する要素を指定し、列の*順序*をリスト表記 `[key1, key2, ...]` で定義します。これにより、正しいキー値が常に予期される列に表示されることを確信できます。最後に、AWS CLI は存在しないキーの値として `None` を出力していることに注目してください。
```
$ aws iam list-users --output text --query 'Users[*].[UserName,Arn,CreateDate,PasswordLastUsed,UserId]'
```
```
Admin arn:aws:iam::123456789012:user/Admin 2014-10-16T16:03:09+00:00 2016-06-03T18:37:29+00:00 AIDA1111111111EXAMPLE
backup-user arn:aws:iam::123456789012:user/backup-user 2019-09-17T19:30:40+00:00 None AIDA2222222222EXAMPLE
cli-user arn:aws:iam::123456789012:user/cli-backup 2019-09-17T19:11:39+00:00 None AIDA3333333333EXAMPLE
```
以下の例では、`grep` および `awk` を `text` コマンドからの `aws ec2 describe-instances` 出力で使用する方法を示しています。最初のコマンドは各インスタンスのアベイラビリティーゾーン、現在の状態、およびインスタンス ID を `text` 出力で表示します。2 番目のコマンドは、その出力を処理して、`us-west-2a` アベイラビリティーゾーンで実行中のすべてのインスタンスのインスタンス ID のみを表示します。
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text
```
```
us-west-2a running i-4b41a37c
us-west-2a stopped i-a071c394
us-west-2b stopped i-97a217a0
us-west-2a running i-3045b007
us-west-2a running i-6fc67758
```
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text | grep us-west-2a | grep running | awk '{print $3}'
```
```
i-4b41a37c
i-3045b007
i-6fc67758
```
次の例は、さらに一歩踏み込んで、出力をフィルタリングする方法だけでなく、その出力を使用して、停止した各インスタンスのインスタンスタイプの変更を自動化する方法も示しています。
```
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[State.Name, InstanceId]' --output text |
> grep stopped |
> awk '{print $2}' |
> while read line;
> do aws ec2 modify-instance-attribute --instance-id $line --instance-type '{"Value": "m1.medium"}';
> done
```
`text` 出力は、PowerShell でも使用できます。`text` 出力の列はタブ区切りであるため、PowerShell の ``t` 区切り文字を使用して、出力を配列に簡単に分割できます。次のコマンドは、最初の列 (`InstanceId`) が文字列 `AvailabilityZone` に一致する場合に 3 列目 (`us-west-2a`) の値を表示します。
```
PS C:\>aws ec2 describe-instances --query 'Reservations[*].Instances[*].[Placement.AvailabilityZone, State.Name, InstanceId]' --output text |
%{if ($_.split("`t")[0] -match "us-west-2a") { $_.split("`t")[2]; } }
```
```
-4b41a37c
i-a071c394
i-3045b007
i-6fc67758
```
前の例では、`--query` パラメータを使用して基になる JSON オブジェクトを解析し、目的の列を取り出す方法を示していますが、PowerShell には、プラットフォーム間の互換性がない場合に JSON を処理する独自の機能があります。ほとんどのコマンドシェルでは、出力をテキストとして扱う必要がありますが、PowerShell では、`ConvertFrom-JSON` コマンドレットを使用して階層構造のオブジェクトを生成できます。その後、そのオブジェクトから必要なメンバーに直接アクセスできます。
```
(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId
```
**ヒント**
テキスト出力を行い、`--query` パラメータを使用して出力を単一のフィールドにフィルタリングすると、出力は 1 行のタブ区切り値になります。次の例に示すように、各値を別々の行に入れるには、出力フィールドを角括弧で囲みます。
タブ区切りの単一の行の出力
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].GroupName"
```
```
HRDepartment Developers SpreadsheetUsers LocalAdmins
```
`[GroupName]` を角括弧で囲むことで、各値を 1 行におさめることができます。
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].[GroupName]"
```
```
HRDepartment
Developers
SpreadsheetUsers
LocalAdmins
```
## テーブルの出力形式
`table` 形式は、複雑な AWS CLI 出力を人間が読み取れる表現で、表形式で生成します。
```
$ aws iam list-users --output table
```
```
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
| ListUsers |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
|| Users ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| Arn | CreateDate | PasswordLastUsed | Path | UserId | UserName ||
|+----------------------------------------------------+---------------------------+---------------------------+----------+-----------------------+-------------+|
|| arn:aws:iam::123456789012:user/Admin | 2014-10-16T16:03:09+00:00 | 2016-06-03T18:37:29+00:00 | / | AIDA1111111111EXAMPLE | Admin ||
|| arn:aws:iam::123456789012:user/backup/backup-user | 2019-09-17T19:30:40+00:00 | | /backup/ | AIDA2222222222EXAMPLE | backup-user ||
|| arn:aws:iam::123456789012:user/cli-user | 2019-09-17T19:11:39+00:00 | | / | AIDA3333333333EXAMPLE | cli-user ||
+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
`--query` オプションを `table` 形式と組み合わせて、raw 出力から事前に選択された要素のセットを表示することができます。ディクショナリ表記とリスト表記の出力の違いに注意してください。最初の例では、列名はアルファベット順ですが、2 番目の例では、名前のない列がユーザーによって定義された順序になっています。`--query` オプションの詳細については、「[Filtering output in the AWS CLI](cli-usage-filter.md)」を参照してください。
```
$ aws ec2 describe-volumes --query 'Volumes[*].{ID:VolumeId,InstanceId:Attachments[0].InstanceId,AZ:AvailabilityZone,Size:Size}' --output table
```
```
------------------------------------------------------
| DescribeVolumes |
+------------+----------------+--------------+-------+
| AZ | ID | InstanceId | Size |
+------------+----------------+--------------+-------+
| us-west-2a| vol-e11a5288 | i-a071c394 | 30 |
| us-west-2a| vol-2e410a47 | i-4b41a37c | 8 |
+------------+----------------+--------------+-------+
```
```
$ aws ec2 describe-volumes --query 'Volumes[*].[VolumeId,Attachments[0].InstanceId,AvailabilityZone,Size]' --output table
```
```
----------------------------------------------------
| DescribeVolumes |
+--------------+--------------+--------------+-----+
| vol-e11a5288| i-a071c394 | us-west-2a | 30 |
| vol-2e410a47| i-4b41a37c | us-west-2a | 8 |
+--------------+--------------+--------------+-----+
```
## オフ出力形式
`off` 形式は、stdout へのすべてのコマンド出力を制限します。これは、出力を処理せずにコマンドの終了コードを確認するだけで済む自動化スクリプトや CI/CD パイプラインに役立ちます。エラーメッセージは引き続き stderr に表示されます。
次の例は、`off` 形式が成功した出力をどのように制限するかを示しています。終了コードを確認して、成功を確認できます。
```
$ aws s3api list-buckets --output off
$ echo $?
0
```
これは、特に出力をキャプチャせずにリソースが存在することを確認するシェルスクリプトに便利です。
```
#!/bin/bash
if aws s3api head-bucket --bucket my-bucket --output off 2>/dev/null; then
echo "Bucket exists"
else
echo "Bucket does not exist"
fi
```
**注記**
`off` 形式は stdout のみを制限します。エラーは引き続き stderr に書き込まれます。
# AWS CLI の構造化エラー出力
このトピックでは、AWS Command Line Interface (AWS CLI) の構造化エラー出力の形式について説明します。CLI は stderr にエラーを書き込み、次の形式をサポートします。
+ **[`enhanced`](#cli-error-format-enhanced)** (デフォルト) - 追加の詳細がインラインで表示されるエラーメッセージ。人間が読み取るデバッグに使用します。
+ **[`json`](#cli-error-format-json)** - 出力は [JSON](https://json.org/) 文字列としてフォーマットされます。オートメーションとスクリプトに使用します。
+ **[`yaml`](#cli-error-format-yaml)** - 出力は [YAML](https://yaml.org/) 文字列としてフォーマットされます。オートメーションとスクリプトに使用します。
+ **[`text`](#cli-error-format-text)** - テキストフォーマットを使用してエラーをフォーマットします。クイックビジュアルスキャンに使用します。
+ **[`table`](#cli-error-format-table)** - テーブルフォーマットを使用してエラーをフォーマットします。クイックビジュアルスキャンに使用します。
+ **[`legacy`](#cli-error-format-legacy)** – 構造化された詳細を含まない元のエラー形式。下位互換性のために使用します。
## エラー形式の設定
エラー形式は、次のいずれかの方法を使用して設定できます。
コマンドラインフラグ
```
$ aws --cli-error-format json
```
設定ファイル (`~/.aws/config`)
```
[default]
cli_error_format = json
```
環境変数
```
$ export AWS_CLI_ERROR_FORMAT=yaml
```
## エラー出力形式
以降のセクションでは、各型式について説明します。
### 拡張形式 (デフォルト)
拡張形式では、エラーメッセージとシンプルな値の追加の詳細がインラインで表示されます。複雑な構造の場合、形式は JSON または YAML を使用するためのヒントを提供します。
**例: リージョン設定がありません**
```
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
```
**例: 追加フィールドを持つ存在しない S3 バケット**
```
aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
Additional error details:
BucketName: amzn-s3-demo-bucket
```
**例: 複雑なエラーフィールド**
```
An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]
Additional error details:
CancellationReasons:
Use "--cli-error-format json" or another error format to see the full details.
```
### JSON 形式
JSON 形式は、すべてのエラーフィールドを含む構造化表現を提供します。
**例: リージョン設定がありません**
```
{
"Code": "NoRegion",
"Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}
```
**例: 存在しない S3 バケット**
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
### YAML 形式
YAML 形式は、すべてのエラーフィールドを含む構造化表現を提供します。
**例: リージョン設定がありません**
```
Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".
```
**例: 存在しない S3 バケット**
```
Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket
```
### テキスト形式
テキスト形式は、成功したコマンド出力と同じフォーマットを使用します。
**例: 存在しない S3 バケット**
```
amzn-s3-demo-bucket NoSuchBucket The specified bucket does not exist
```
### テーブル形式
テーブル形式は、成功したコマンド出力と同じフォーマットを使用します。
**例: 存在しない S3 バケット**
```
-------------------------------------------------------------------------------------|
| error |
+---------------------------+---------------+----------------------------------------+
| BucketName | Code | Message |
+---------------------------+---------------+----------------------------------------+
| amzn-s3-demo-bucket | NoSuchBucket | The specified bucket does not exist |
+---------------------------+---------------+----------------------------------------+
```
### 従来の形式
従来の形式は、構造化された詳細のない元のエラー形式を提供します。この形式には、CLI 例外の「An error occurred (ErrorCode):」プレフィックスは含まれません。
**例: リージョン設定がありません**
```
aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".
```
**例: 存在しない S3 バケット**
```
An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
```
**注記**
エラーに、CLI 例外の `aws: [ERROR]:` プレフィックスが一貫して含まれるようになりました。以前のバージョンには、このプレフィックスが常に含まれていたわけではありません。
次の例外は、設定されたエラー形式に関係なく、常に従来の形式を使用します。
`UnknownArgumentError` - 使用状況の情報を表示します
キーボード割り込み (`KeyboardInterrupt`)
## 完全な例
次の例は、JSON エラー形式のコマンドを示しています。
```
$ aws s3api get-object \
--bucket amzn-s3-demo-bucket \
--key file.txt out.txt \
--cli-error-format json
```
出力 (stderr):
```
{
"Code": "NoSuchBucket",
"Message": "The specified bucket does not exist",
"BucketName": "amzn-s3-demo-bucket"
}
```
`BucketName` フィールドは、Amazon S3 サービスによって返されるモデル化されたエラーメンバーです。
# Using the pagination options in the AWS CLI
このトピックでは、AWS Command Line Interface (AWS CLI) からの出力をページネーションするためのさまざまな方法を示します。
からページネーションを制御する方法は主に 2 つありますAWS CLI
+ [サーバー側のページ分割パラメータの使用。](#cli-usage-pagination-serverside)
+ [出力用のデフォルトのクライアント側のページングプログラムの使用](#cli-usage-pagination-clientside)。
サーバー側のページ分割パラメータが最初に処理され、出力がクライアント側のページ分割に送信されます。
## サーバー側のページ分割
項目の大きなリストを返すほとんどのコマンドの場合、AWS CLI がサービスの API を呼び出してリストを生成するときに出力に含める項目の数を制御するための複数のオプションが AWS CLI にあります。AWS CLI のサーバー側ページ分割は AWS のサービス API によって有効になるため、これらのオプションはサービス API が有効にしている場合にのみ機能します。
**Topics**
+ [--no-paginate](#cli-usage-pagination-nopaginate)
+ [--page-size](#cli-usage-pagination-pagesize)
+ [--max-items](#cli-usage-pagination-maxitems)
+ [--starting-token](#cli-usage-pagination-startingtoken)
デフォルトでは、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 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)を参照してください。
### --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` 変数を空の文字列に設定する。
**Topics**
+ [cli\$1pager](#cli-usage-pagination-clipager)
+ [AWS\$1PAGER](#cli-usage-pagination-awspager)
+ [--no-cli-pager](#cli-usage-pagination-noclipager)
+ [ページャーフラグ](#cli-usage-pagination-flags)
### cli\$1pager 設定の使用方法
頻繁に利用される構成設定および認証情報を AWS CLI が維持するファイルに保存することができます。名前プロファイルの設定は、`default` プロファイルの設定よりも優先されます。構成設定の詳細については、「[Configuration and credential file settings in the AWS CLI](cli-configure-files.md)」を参照してください。
次の例では、デフォルトの出力ページャーを `less` プログラムに設定します。
```
[default]
cli_pager=less
```
以下の例では、ページャーの使用を無効にするようにデフォルトを設定します。
```
[default]
cli_pager=
```
### AWS\$1PAGER 環境変数の設定方法
次の例では、デフォルトの出力ページャーを `less` プログラムに設定します。環境変数の詳細については、「[Configuring environment variables for the AWS CLI](cli-configure-envvars.md)」を参照してください。
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### --no-cli-pager オプションの使用方法
1 つのコマンドでのページャーの使用を無効にするには、`--no-cli-pager` オプションを使用します。コマンドラインオプションの詳細については、「[Command line options in the AWS CLI](cli-configure-options.md)」を参照してください。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-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](http://manpages.org/less/1#options)」を参照してください。
------
#### [ Windows ]
特に指定しない場合、AWS CLI バージョン 2 がデフォルトで使用するページャーは `more` で、追加のフラグはありません。
次の例では、`/c` パラメータを使用しています
```
C:\> setx AWS_PAGER "more /c"
```
`more` フラグの詳細については、*Microsoft Docs* の「`[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)`」を参照してください。
------
# Filtering output in the AWS CLI
AWS Command Line Interface (AWS CLI) には、サーバー側とクライアント側の両方のフィルタリングがあり、AWS CLI 出力をフィルタリングするために個別または一緒に使用することができます。サーバー側のフィルタリングが最初に処理され、クライアント側のフィルタリングのために出力が返されます。
+ サーバー側のフィルタリングは API によってサポートされており、通常は `--filter` パラメータを使用して実装します。このサービスは一致する結果のみを返し、大きなデータセットの HTTP レスポンス時間を短縮できます。
+ クライアント側のフィルタリングは、AWS CLI パラメータを使用して `--query` クライアントによってサポートされます。このパラメータには、サーバー側のフィルタリングにはない可能性がある機能があります。
**Topics**
+ [サーバー側のフィルタリング](#cli-usage-filter-server-side)
+ [クライアント側のフィルタリング](#cli-usage-filter-client-side)
+ [サーバー側とクライアント側のフィルタリングを組み合わせる](#cli-usage-filter-combining)
+ [その他のリソース](#cli-usage-filter-resources)
## サーバー側のフィルタリング
AWS CLI でのサーバー側のフィルタリングは、AWS サービス API によって提供されます。AWS サービスは、フィルターに一致する HTTP レスポンス内のレコードのみを返します。これにより、大規模なデータセットの HTTP レスポンス時間が短縮されます。サーバー側のフィルタリングはサービス API によって定義されるため、パラメータ名と関数はサービスによって異なります。フィルタリングに使用される一般的なパラメータ名は次のとおりです。
+ `--filter` ( [ses](https://docs.aws.amazon.com/cli/latest/reference/ses/create-receipt-filter.html)、 [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html)など)。
+ `--filters` ( [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html)、 [autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html)、 [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) など)。
+ 単語「`filter`」で始まる名前 ([https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html) コマンドの `--filter-expression` など)。
特定のコマンドにサーバー側のフィルタリングとフィルタリングルールがあるかどうかについては、「[AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)」を参照してください。
## クライアント側のフィルタリング
AWS CLI は、`--query` パラメータによって、組み込みの JSON ベースのクライアント側のフィルタリング機能を提供します。`--query` パラメータは、出力の内容とスタイルをカスタマイズするために使用できる強力なツールです。`--query` パラメータは、サーバーから返される HTTP レスポンスを受け取り、結果を表示する前にフィルタリングします。フィルタリングする前に HTTP レスポンス全体がクライアントに送信されるため、大規模なデータセットでは、クライアント側のフィルタリングはサーバー側のフィルタリングよりも遅くなる可能性があります。
クエリでは、[JMESPath 構文](https://jmespath.org/)を使用して、出力をフィルタリングするための式を作成します。JMESPath 構文については、*JMESPath ウェブサイト*の「[Tutorial](https://jmespath.org/tutorial.html)」をご参照ください。
**重要**
指定する出力タイプによって、`--query` オプションの動作が変更されます。
`--output text` を指定する場合、出力は `--query` フィルターが適用される*前に*ページ分割され、AWS CLI は出力の*各ページ*でクエリを 1 回実行します。このため、クエリには各ページで最初に一致する要素が含まれており、予期しない余分な出力が発生する可能性があります。出力をさらにフィルタリングするには、`head` や `tail` などの他のコマンドラインツールを使用できます。
`--output json`、 `--output yaml`、`--output yaml-stream` を指定する場合、単一のネイティブな構造として完全に処理されてから `--query` フィルターが適用されます。AWS CLI は構造全体に対してクエリを 1 回だけ実行し、フィルタリングされた結果を生成してから出力されます。
**Topics**
+ [開始する前に](#cli-usage-filter-client-side-output)
+ [識別子](#cli-usage-filter-client-side-identifiers)
+ [リストから選択する](#cli-usage-filter-client-side-select-list)
+ [ネストされたデータをフィルタリングする](#cli-usage-filter-client-side-nested)
+ [結果をフラット化する](#cli-usage-filter-client-side-specific-flattening)
+ [特定の値をフィルタリングする](#cli-usage-filter-client-side-specific-values)
+ [パイピング式](#cli-usage-filter-client-side-pipe)
+ [複数の識別子の値をフィルタリングする](#cli-usage-filter-client-side-miltiselect-list)
+ [識別子の値にラベルを追加する](#cli-usage-filter-client-side-multiselect-hash)
+ [関数](#cli-usage-filter-client-side-functions)
+ [高度な `--query` の例](#cli-usage-filter-client-side-advanced)
### 開始する前に
**注記**
これらのフィルタ式の例は、基本的な Linux 系シェル用に記述されています。これらの例を使用する場合は、ターミナルシェルに正しい引用規則を使用してください。ターミナルが入力を解釈する方法によって、AWS CLI に送信される内容が大きく変わることがあります。ターミナルが一重引用符 `'`、二重引用符 `"`、またはバックティック ``` をどのように解釈するかによって、内容の読み取り方が変わることがあります。
詳細については、「[Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md)」を参照してください。
次の JSON 出力は、`--query` パラメータが生成できるものの例を示しています。出力は、個別の Amazon EC2 インスタンスにアタッチされた 3 つの Amazon EBS ボリュームについて説明しています。
#### 出力例
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
### 識別子
識別子は、出力値のラベルです。フィルターを作成するときは、識別子を使用してクエリ結果を絞り込みます。次の出力例では、`Volumes`、`AvailabilityZone`、`AttachTime` などのすべての識別子が強調表示されます。
```
$ aws ec2 describe-volumes
{
"Volumes": [
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
}
```
詳細については、*JMESPath ウェブサイト*の「[Identifiers](https://jmespath.org/specification.html#identifiers )」をご参照ください。
### リストから選択する
リストまたは配列は、`[` における `Volumes` や `Attachments` などの角括弧「[開始する前に](#cli-usage-filter-client-side-output)」の後に続く識別子です。
**構文**
```
[ ]
```
配列からのすべての出力をフィルタリングするには、ワイルドカード表記を使用できます。[ワイルドカード](http://jmespath.org/specification.html#wildcard-expressions)式は、`*` 表記法を使用して要素を返すために使用される式です。
次の例では、すべての `Volumes` コンテンツに対するクエリを実行します。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
配列内の特定のボリュームをインデックス別に表示するには、配列インデックスを呼び出します。例えば、`Volumes` 配列の最初の項目のインデックスは 0 で、`Volumes[0]` クエリが生成されます。配列インデックスの詳細については、*JMESPath ウェブサイト*の「[index expressions](http://jmespath.org/specification.html#index-expressions)」をご参照ください。
```
$ aws ec2 describe-volumes \
--query 'Volumes[0]'
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
```
ボリュームの特定範囲をインデックス別に表示するには、次の構文とともに `slice` を使用します。ここで、**start** は開始配列インデックス、**stop** はフィルターが処理を停止するインデックス、**step** はスキップ間隔です。
**構文**
```
[::]
```
スライス式からこれらのいずれかを省略すると、次のデフォルト値が使用されます。
+ Start - リストの最初のインデックス、0。
+ Stop - リストの最後のインデックス。
+ Step - ステップスキップなし。値は 1 です。
最初の 2 つのボリュームだけを返すには、次の例に示すように、start 値 0、stop 値 2、step 値 1 を使用します。
```
$ aws ec2 describe-volumes \
--query 'Volumes[0:2:1]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-2e410a47",
"State": "in-use",
"SnapshotId": "snap-708e8348",
"CreateTime": "2013-09-18T20:26:15.000Z",
"Size": 8
}
]
```
この例にはデフォルト値が含まれているため、スライスを `Volumes[0:2:1]` から `Volumes[:2]` に短縮できます。
次の例では、デフォルト値を省略し、配列全体におけるあらゆる 2 つのボリュームを返します。
```
$ aws ec2 describe-volumes \
--query 'Volumes[::2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
}
]
```
次の例に示すように、step には、配列の逆の順序でフィルタリングするために負の数を使用することもできます。
```
$ aws ec2 describe-volumes \
--query 'Volumes[::-2]'
[
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-a1b3c7nd",
"State": "in-use",
"SnapshotId": "snap-234087fb",
"CreateTime": "2020-11-20T19:54:05.000Z",
"Size": 15
},
{
"AvailabilityZone": "us-west-2a",
"Attachments": [
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
"VolumeType": "standard",
"VolumeId": "vol-e11a5288",
"State": "in-use",
"SnapshotId": "snap-f23ec1c8",
"CreateTime": "2013-09-17T00:55:03.000Z",
"Size": 30
}
]
```
詳細については、*JMESPath ウェブサイト*の「[Slices](https://jmespath.org/specification.html#slices)」をご参照ください。
### ネストされたデータをフィルタリングする
ネストされた値の `Volumes[*]` のフィルタリング結果を絞り込むには、ピリオドとフィルター条件を追加して部分式を使用します。
**構文**
```
.
```
次の例は、すべてのボリュームのすべての `Attachments` 情報を示しています。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments'
[
[
{
"AttachTime": "2013-09-17T00:55:03.000Z",
"InstanceId": "i-a071c394",
"VolumeId": "vol-e11a5288",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2013-09-18T20:26:16.000Z",
"InstanceId": "i-4b41a37c",
"VolumeId": "vol-2e410a47",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
],
[
{
"AttachTime": "2020-11-20T19:54:06.000Z",
"InstanceId": "i-1jd73kv8",
"VolumeId": "vol-a1b3c7nd",
"State": "attached",
"DeleteOnTermination": true,
"Device": "/dev/sda1"
}
]
]
```
ネストされた値までさらに絞り込むには、ネストされた各識別子の式を追加します。次の例では、すべての `State` の `Volumes` をリストします。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[*].State'
[
[
"attached"
],
[
"attached"
],
[
"attached"
]
]
```
### 結果をフラット化する
詳細については、*JMESPath ウェブサイト*の「[SubExpressions](https://jmespath.org/specification.html#subexpressions)」をご参照ください。
`Volumes[*].Attachments[*].State` クエリの結果として生成されたワイルドカード表記を削除することで、`Volumes[*].Attachments[].State` の結果をフラット化することができます。フラット化は、多くの場合、結果の可読性を向上させるのに役立ちます。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].State'
[
"attached",
"attached",
"attached"
]
```
詳細については、*JMESPath ウェブサイト*の「[Flatten](https://jmespath.org/specification.html#flatten)」をご参照ください。
### 特定の値をフィルタリングする
リスト内の特定の値をフィルタリングするには、次の構文に示すように、フィルター式を使用します。
**構文**
```
? ]
```
式の比較演算子には、`==`、`!=`、`<`、`<=`、`>`、`>=` などがあります。次の例では、`VolumeIds` `Volumes` のすべての `Attached` の `State` をフィルタリングします。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId'
[
[
"vol-e11a5288"
],
[
"vol-2e410a47"
],
[
"vol-a1b3c7nd"
]
]
```
その後、これをフラット化することができ、次の例になります。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[?State==`attached`].VolumeId[]'
[
"vol-e11a5288",
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
次の例では、サイズが 20 未満のすべての `VolumeIds` の `Volumes` をフィルタリングします。
```
$ aws ec2 describe-volumes \
--query 'Volumes[?Size < `20`].VolumeId'
[
"vol-2e410a47",
"vol-a1b3c7nd"
]
```
詳細については、*JMESPath ウェブサイト*の「[Filter Expressions](https://jmespath.org/specification.html#filterexpressions)」をご参照ください。
### パイピング式
フィルターの結果を新しいリストにパイプ処理し、次の構文を使用して別の式で結果をフィルタリングできます。
**構文**
```
| ]
```
次の例では、`Volumes[*].Attachments[].InstanceId` 式のフィルタリング結果を取得し、配列の最初の結果を出力します。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId | [0]'
"i-a071c394"
```
この例では、最初に次の式から配列を作成することによってこれを行います。
```
$ aws ec2 describe-volumes \
--query 'Volumes[*].Attachments[].InstanceId'
"i-a071c394",
"i-4b41a37c",
"i-1jd73kv8"
```
その後、その配列の最初の要素を返します。
```
"i-a071c394"
```
詳細については、*JMESPath ウェブサイト*の「[Pipe Expressions](https://jmespath.org/specification.html#pipe-expressions)」をご参照ください。
### 複数の識別子の値をフィルタリングする
複数の識別子をフィルタリングするには、次の構文を使用して、複数選択リストを使用します。
**構文**
```
[].[, ]
```
次の例では、`VolumeId` および `VolumeType` が `Volumes` リストでフィルタリングされ、次の式になります。
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType]'
[
[
"vol-e11a5288",
"standard"
],
[
"vol-2e410a47",
"standard"
],
[
"vol-a1b3c7nd",
"standard"
]
]
```
ネストされたデータをリストに追加するには、別の複数選択リストを追加します。次の例では、ネストされた `InstanceId` リストの `State` および `Attachments` もフィルタリングすることによって、前の例を拡張します。これにより、式は次のようになります。
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State]]'
[
[
"vol-e11a5288",
"standard",
[
[
"i-a071c394",
"attached"
]
]
],
[
"vol-2e410a47",
"standard",
[
[
"i-4b41a37c",
"attached"
]
]
],
[
"vol-a1b3c7nd",
"standard",
[
[
"i-1jd73kv8",
"attached"
]
]
]
]
```
可読性を向上させるには、次の例に示すように、式をフラット化します。
```
$ aws ec2 describe-volumes \
--query 'Volumes[].[VolumeId, VolumeType, Attachments[].[InstanceId, State][]][]'
[
"vol-e11a5288",
"standard",
[
"i-a071c394",
"attached"
],
"vol-2e410a47",
"standard",
[
"i-4b41a37c",
"attached"
],
"vol-a1b3c7nd",
"standard",
[
"i-1jd73kv8",
"attached"
]
]
```
詳細については、*JMESPath ウェブサイト*の「[Multiselect list](https://jmespath.org/specification.html#multiselectlist)」をご参照ください。
### 識別子の値にラベルを追加する
この出力を読みやすくするには、次の構文で複数選択ハッシュを使用します。
**構文**
```
[].{