# 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 に書き込まれます。