# AWS CLI を使用する場合
このセクションでは、設定の「[Using endpoints in the AWS CLI](cli-configure-endpoints.md)」セクションで説明されている詳細から一歩進んで、一般的な使用方法、一般的な機能、および AWS Command Line Interface (AWS CLI) で利用可能なオプションの概要を説明します。
このガイドでは、基本的構造、フォーマット、フィルタリング機能など、AWS CLI コマンドの記述に関する基本的側面について詳しく説明します。これらのコア要素を理解することで、複雑なウェブベースのコンソールを操作することなく、確実に必要なリソースとアクションをターゲットとするコマンドを構築できます。
さらに、AWS CLI で利用できるヘルプコンテンツとドキュメントが強調表示されます。組み込みコマンドラインヘルプから包括的な「」「[AWS CLIバージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/)」まで、AWS CLI の機能と能力を確認するのに役立つ情報にアクセスできます。
AWS のサービス の具体的な例とユースケースについては、「[AWS CLI の例](cli-chap-code-examples.md)」または「」「[AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/)」を参照してください。これらにコマンド固有の情報が記載されており、さまざまな AWS のサービスで AWS CLIを活用する方法の例を示します。
**注記**
デフォルトでは、AWS CLI が TCP ポート 443 で HTTPS を使用することによって、リクエストを AWS のサービスに送信します。AWS CLI を正常に使用するには、このポートでアウトバウンド接続が可能である必要があります。
**Topics**
+ [Accessing help and resources for the AWS CLI](cli-usage-help.md)
+ [AWS CLI のコマンド構造](cli-usage-commandstructure.md)
+ [AWS CLI でのパラメータ値の指定](cli-usage-parameters.md)
+ [AWS CLI でのコマンドプロンプトの有効化と使用](cli-usage-parameters-prompting.md)
+ [Controlling command output in the AWS CLI](cli-usage-output.md)
+ [AWS CLI でのコマンドラインのリターンコード](cli-usage-returncodes.md)
+ [カスタムウィザードを使用して AWS CLI でインタラクティブコマンドを実行する](cli-usage-wizard.md)
+ [Creating and using aliases in the AWS CLI](cli-usage-alias.md)
+ [AWS CLI のエラーのトラブルシューティング](cli-chap-troubleshooting.md)
# Accessing help and resources for the AWS CLI
このトピックでは、AWS Command Line Interface (AWS CLI) のヘルプコンテンツにアクセスする方法について説明します。
**Topics**
+ [組み込みの AWS CLI help コマンド](#cli-usage-help-command)
+ [AWS CLI リファレンスガイド](#cli-reference)
+ [API ドキュメント](#api-reference)
+ [エラーのトラブルシューティング](#help-tshoot)
+ [その他のヘルプ](#help-additional)
## 組み込みの AWS CLI help コマンド
AWS Command Line Interface (AWS CLI) を使用している場合は、どのコマンドのヘルプも表示できます。そのためには、コマンド名の末尾に `help` と入力するだけです。
例えば、次のコマンドは、一般的な AWS CLI オプションと使用可能な最上位レベルのコマンドに関するヘルプを表示します。
```
$ aws help
```
次のコマンドは、利用可能な Amazon Elastic Compute Cloud (Amazon EC2) 固有のコマンドを表示します。
```
$ aws ec2 help
```
次の例は、Amazon EC2 `DescribeInstances` オペレーションの詳細なヘルプを表示します。ヘルプには、入力パラメータ、使用可能なフィルター、および出力に含まれるものについての説明があります。コマンドの一般的なバリエーションを入力する方法を示す例も含まれています。
```
$ aws ec2 describe-instances help
```
バージョン `2.31.0` における `help` コマンドの表示は `cli_help_output` 設定で設定され、次の値があります。
+ **(デフォルト)** `terminal` - ターミナルで man ページを開きます。
+ `browser` - デフォルトのブラウザで man ページをローカル HTML ファイルとして開きます。デフォルトのブラウザを開くと、ターミナルに通知が出力され、AWS CLI がブラウザを開くことができない場合はエラーメッセージが表示されます。
+ `url` - インストールした AWS CLI のバージョンに関するオンライン AWS CLI リファレンスガイドの URL を出力します。`AWS_PAGER` 環境変数など、クライアント側のページングの設定が優先されます。
各コマンドのヘルプは 6 つのセクションに分かれています。
名前
コマンドの名前。
```
NAME
describe-instances -
```
説明
コマンドが呼び出す API 操作の説明。
```
DESCRIPTION
Describes one or more of your instances.
If you specify one or more instance IDs, Amazon EC2 returns information
for those instances. If you do not specify instance IDs, Amazon EC2
returns information for all relevant instances. If you specify an
instance ID that is not valid, an error is returned. If you specify an
instance that you do not own, it is not included in the returned
results.
...
```
概要
コマンドとそのオプションを使用するための基本的な構文。オプションが角括弧で示されている場合は、そのオプションが任意である、デフォルト値がある、または使用できる代替オプションがあることを意味しています。
```
SYNOPSIS
describe-instances
[--dry-run | --no-dry-run]
[--instance-ids ]
[--filters ]
[--cli-input-json ]
[--starting-token ]
[--page-size ]
[--max-items ]
[--generate-cli-skeleton]
```
たとえば、`describe-instances` のデフォルトの動作では、現在のアカウントおよび AWS リージョン内の***すべて***のインスタンスを記述します。必要に応じて `instance-ids` のリストを指定して、1 つ以上のインスタンスを定義することもできます。`dry-run` は値を取らないオプションのブールフラグです。ブールフラグを使用するには、表示される値のいずれかを指定します。この場合は `--dry-run` または `--no-dry-run` です。同様に、`--generate-cli-skeleton` も値を取りません。オプションの使用に条件がある場合は、`OPTIONS` セクションで説明されるか、例に示されます。
オプション
Synopsis に示される各オプションの説明。
```
OPTIONS
--dry-run | --no-dry-run (boolean)
Checks whether you have the required permissions for the action,
without actually making the request, and provides an error response.
If you have the required permissions, the error response is DryRun-
Operation . Otherwise, it is UnauthorizedOperation .
--instance-ids (list)
One or more instance IDs.
Default: Describes all your instances.
...
```
例
コマンドとそのオプションの使用方法を示す例。必要なコマンドまたはユースケースについて例がない場合は、このページまたはコマンドのヘルプページの AWS CLI コマンドリファレンスにあるフィードバックリンクを使用してリクエストしてください。
```
EXAMPLES
To describe an Amazon EC2 instance
Command:
aws ec2 describe-instances --instance-ids i-5203422c
To describe all instances with the instance type m1.small
Command:
aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small"
To describe all instances with an Owner tag
Command:
aws ec2 describe-instances --filters "Name=tag-key,Values=Owner"
...
```
出力
からの応答に含まれる各フィールドとデータタイプの説明AWS
`describe-instances` の場合は、出力は予約オブジェクトのリストであり、それぞれのオブジェクトに、関連付けられたインスタンスに関する情報を含む複数のフィールドとオブジェクトがあります。この情報は、Amazon EC2 で使用される[予約データタイプの API ドキュメント](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Reservation.html)から取得されます。
```
OUTPUT
Reservations -> (list)
One or more reservations.
(structure)
Describes a reservation.
ReservationId -> (string)
The ID of the reservation.
OwnerId -> (string)
The ID of the AWS account that owns the reservation.
RequesterId -> (string)
The ID of the requester that launched the instances on your
behalf (for example, AWS Management Console or Auto Scaling).
Groups -> (list)
One or more security groups.
(structure)
Describes a security group.
GroupName -> (string)
The name of the security group.
GroupId -> (string)
The ID of the security group.
Instances -> (list)
One or more instances.
(structure)
Describes an instance.
InstanceId -> (string)
The ID of the instance.
ImageId -> (string)
The ID of the AMI used to launch the instance.
State -> (structure)
The current state of the instance.
Code -> (integer)
The low byte represents the state. The high byte
is an opaque internal value and should be ignored.
...
```
出力が AWS CLI によって JSON にレンダリングされるときには、次の例と同様の予約オブジェクトの配列になります。
```
{
"Reservations": [
{
"OwnerId": "012345678901",
"ReservationId": "r-4c58f8a0",
"Groups": [],
"RequesterId": "012345678901",
"Instances": [
{
"Monitoring": {
"State": "disabled"
},
"PublicDnsName": "ec2-52-74-16-12.us-west-2.compute.amazonaws.com",
"State": {
"Code": 16,
"Name": "running"
},
...
```
各予約オブジェクトには、予約およびインスタンスオブジェクトの配列を説明するフィールドがあり、それぞれにそれを説明する独自のフィールド (例: `PublicDnsName`) とオブジェクト (例: `State`) があります。
**Windows ユーザー**
ヘルプコマンドの出力を `more` コマンドに*パイプ* (\$1) して、ヘルプファイルを 1 ページずつ表示することができます。スペースバーまたは **PgDn** を押すと、ドキュメントの続きが表示され、**q** を押すと終了します。
```
C:\> aws ec2 describe-instances help | more
```
## AWS CLI リファレンスガイド
ヘルプファイルには、コマンドラインからは表示や移動ができないリンクが含まれています。オンラインの [AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)のリンクを利用することで、表示および操作できます。リファレンスには、すべての AWS CLI コマンドのヘルプコンテンツも含まれています。説明は、モバイル、タブレット、またはデスクトップ画面で移動や表示がしやすいように表示されます。
## API ドキュメント
AWS CLI のすべてのコマンドは、AWS サービスのパブリック API に対して行われるリクエストに対応しています。パブリック API を使用する各サービスには API リファレンスがあり、これらは [AWS ドキュメントウェブサイト](https://docs.aws.amazon.com/)にあるサービスのホームページに記載されています。API リファレンスの内容は、API の構築方法および使用されているプロトコルによって異なります。通常、API リファレンスには、API によってサポートされるオペレーション、サービスとの間で送受信されるデータ、およびサービスが報告するエラー条件に関する詳細情報が含まれています。
**API ドキュメントセクション**
+ **アクション ** - 各オペレーションとそのパラメータに関する詳細情報 (長さまたは内容に関する制約、デフォルト値を含む)。このオペレーションで発生する可能性のあるエラーが一覧表示されます。各オペレーションは、AWS CLI のサブコマンドに対応します。
+ **データタイプ ** - コマンドが必要なパラメータそして、リクエストに応答して返す構造体に関する詳細情報。
+ **Common Parameters ** - サービスのすべてのアクションに共通のパラメータに関する詳細情報。
+ **Common Errors ** - サービスの操作によって返される可能性のあるエラーに関する詳細情報。
各セクションの名前と有無は、サービスによって異なる場合があります。
**サービス固有の CLI**
一部のサービスには、すべてのサービスで動作するように単一の AWS CLI が作成される前から存在する個別の CLI があります。これらのサービス固有の CLI には、サービスのドキュメントページからリンクされた個別のドキュメントがあります。サービス固有の CLI のドキュメントは AWS CLI には適用されません。
## エラーのトラブルシューティング
AWS CLI エラーの診断と修正に関するヘルプについては、「[AWS CLI のエラーのトラブルシューティング](cli-chap-troubleshooting.md)」を参照してください。
## その他のヘルプ
AWS CLI の問題に関する追加のヘルプについては、*GitHub* の [AWS CLI コミュニティ](https://github.com/aws/aws-cli/issues)にアクセスしてください。
# AWS CLI のコマンド構造
このトピックでは、AWS Command Line Interface (AWS CLI) コマンドの構造と、wait コマンドの使用方法について説明します。
**Topics**
+ [コマンド構造](#cli-usage-commandstructure-structure.title)
+ [Wait コマンド](#cli-usage-commandstructure-wait)
## コマンド構造
AWS CLI は、コマンドラインでマルチパート構造を使用し、それは次の順序で指定される必要があります。
1. `aws` プログラムのベースコール。
1. 最上位レベルの *コマンド*。一般に AWS によってサポートされる AWS CLI サービスに対応します。
1. 実行する操作を指定する*サブコマンド*。
1. 操作に必要となる一般的な AWS CLI オプションまたはパラメータ。これらは、最初の 3 つのパートに続く限り、任意の順序で指定することができます。排他的パラメータが複数回指定された場合は、*最後の値*のみ適用されます。
```
$ aws [options and parameters]
```
パラメータは数値、文字列、リスト、マップ、JSON 構造体など、様々なタイプの入力値を取得できます。サポートされる内容は、指定したコマンドおよびサブコマンドによって異なります。
### 例
**Amazon S3**
次の例では、すべての Amazon S3 バケットを一覧表示します。
```
$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2
```
Amazon S3 コマンドの詳細については、*AWS CLI* コマンドリファレンスの「[https://docs.aws.amazon.com/cli/latest/reference/s3/index.html](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html)」を参照してください。
**AWS CloudFormation**
以下の [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-change-set.html) コマンドの例は、CloudFormation スタック名を *my-change-set* に変更します。
```
$ aws cloudformation create-change-set --stack-name my-stack --change-set-name my-change-set
```
AWS CloudFormation コマンドの詳細については、*AWS CLI コマンドリファレンス* の「[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/index.html)」を参照してください。
## Wait コマンド
一部の AWS のサービスでは、`wait` コマンドを使用できます。`aws wait` を使用するコマンドは、通常、コマンドが完了するまで待機してから、次のステップに進みます。wait コマンドを使用すると、wait コマンドが失敗した場合に後続のステップに移動するのを防ぐことができるため、マルチパートコマンドやスクリプトに特に便利です。
AWS CLI は、`wait` コマンドのコマンドラインでマルチパート構造を使用します。それは次の順序で指定される必要があります。
1. `aws` プログラムのベースコール。
1. 最上位レベルの *コマンド*。一般に AWS によってサポートされる AWS CLI サービスに対応します。
1. `wait` コマンド。
1. 実行する操作を指定する*サブコマンド*。
1. 操作に必要な一般的な CLI オプションまたはパラメータ。これらは、最初の 3 つのパートに続く限り、任意の順序で指定することができます。排他的パラメータが複数回指定された場合は、*最後の値*のみ適用されます。
```
$ aws wait [options and parameters]
```
パラメータは数値、文字列、リスト、マップ、JSON 構造体など、様々なタイプの入力値を取得できます。サポートされる内容は、指定したコマンドおよびサブコマンドによって異なります。
**注記**
すべての AWS のサービスが `wait` コマンドをサポートしているわけではありません。ご使用のサービスが `wait` コマンドをサポートしているかどうかについては、[AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)を参照してください。
### 例
**AWS CloudFormation**
次の [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) コマンドの例は、*my-stack* スタック内の *my-change-set* 変更セットの実行準備が整っていることを確認できる場合に限り、一時停止と再開を行います。
```
$ aws cloudformation wait change-set-create-complete --stack-name my-stack --change-set-name my-change-set
```
AWS CloudFormation `wait`コマンドの詳細については、*AWS CLI* コマンドリファレンスの「[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html)」を参照してください。
**AWS CodeDeploy**
次の [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/change-set-create-complete.html) コマンド例は、*d-A1B2C3111* のデプロイが正常に完了するまで一時停止します。
```
$ aws deploy wait deployment-successful --deployment-id d-A1B2C3111
```
AWS CodeDeploy `wait`コマンドの詳細については、*AWS CLI コマンドリファレンス*の「[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/wait/index.html)」を参照してください。
# AWS CLI でのパラメータ値の指定
AWS Command Line Interface (AWS CLI) で使用される多くのパラメータは、以下の `aws ec2 create-key-pair` コマンド例のキーペア名 `my-key-pair` などのように、単純な文字列または数値です。
```
$ aws ec2 create-key-pair --key-name my-key-pair
```
コマンドのフォーマットは、ターミナルによって異なる場合があります。たとえば、ほとんどのターミナルは大文字と小文字を区別しますが、Powershell は大文字と小文字を区別しません。つまり、以下の 2 つのコマンド例では、`MyFile*.txt` と `myfile*.txt` を**異なる**パラメータとして表示するため、大文字と小文字が区別されるターミナルでは異なる結果になります。
ただし、PowerShell はこれらのリクエストを、`MyFile*.txt` と `myfile*.txt` を**同じ**パラメータと見なすのと同じように処理します。次のコマンド例は、`aws s3 cp` コマンドを使用したこれらのパラメータを示しています。
```
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "MyFile*.txt"
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "myfile*.txt"
```
PowerShell で大文字と小文字が区別されないことの詳細については、*PowerShell のドキュメント*の「[about\$1Case-Sensitivity](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity)」を参照してください。
特殊文字やスペース文字を含む文字列を引用符やリテラルで囲む必要がある場合があります。このフォーマットに関する規則は、ターミナルによっても異なる場合があります。複雑なパラメータを引用符で囲む方法の詳細については、「[Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md)」を参照してください。
これらのトピックでは、最も一般的なターミナルフォーマットルールについて説明します。ターミナルでパラメータ値を認識できない場合は、このセクションのトピックを確認し、ターミナルのドキュメントで特定の構文ルールを確認してください。
**Topics**
+ [Common parameter types in the AWS CLI](cli-usage-parameters-types.md)
+ [Using quotation marks and literals with strings in the AWS CLI](cli-usage-parameters-quoting-strings.md)
+ [AWS CLI でのファイルからのパラメータの読み込み](cli-usage-parameters-file.md)
+ [AWS CLI skeletons and input files in the AWS CLI](cli-usage-skeleton.md)
+ [Using shorthand syntax in the AWS CLI](cli-usage-shorthand.md)
# Common parameter types in the AWS CLI
このセクションでは、いくつかの一般的なパラメータタイプと一般的に必要な形式について説明します。
特定のコマンドでパラメータの書式化に問題がある場合には、コマンド名の後に **help** と入力することによって、ヘルプを確認してみてください。各サブコマンドのヘルプには、オプションの名前と説明が示されています。オプションのパラメータタイプは、括弧内に一覧表示されています。ヘルプ表示の詳細については、「[Accessing help and resources for the AWS CLI](cli-usage-help.md)」を参照してください。
**Topics**
+ [String](#parameter-type-string)
+ [タイムスタンプ](#parameter-type-timestamp)
+ [リスト](#parameter-type-list)
+ [ブール値](#parameter-type-boolean)
+ [整数](#parameter-type-integer)
+ [バイナリ/blob (バイナリラージオブジェクト) とストリーミング blob](#parameter-type-blobs)
+ [マップ](#parameter-type-map)
+ [ドキュメント](#parameter-type-document)
## String
文字列パラメータには、[ASCII](https://wikipedia.org/wiki/ASCII) 文字セットの英数字、記号、空白文字が使用できます。空白文字を含む文字列は引用符で囲まれている必要があります。予期しない結果を避けるため、標準の空白文字以外の記号や空白文字は使用せず、お使いの端末の[引用符のルール](cli-usage-parameters-quoting-strings.md)に従うことをお勧めします。
一部の文字列パラメータはファイルからバイナリデータを受け取ることができます。例については、「[バイナリファイル](cli-usage-parameters-file.md#cli-usage-parameters-file-binary)」を参照してください。
## タイムスタンプ
タイムスタンプの形式は [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 標準に従います。これらは「`DateTime`」または「`Date`」パラメータと呼ばれることもあります。
```
$ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z
```
有効な形式は次のとおりです。
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (UTC)* (例: 2014-10-01T20:30:00.000Z)
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (オフセットあり)* (例: 2014-10-01T12:30:00.000-08:00)
+ *YYYY*-*MM*-*DD* (例: 2014-10-01)
+ Unix 時間 (秒)、例: 1412195400。これは [Unix エポック時間](https://wikipedia.org/wiki/Unix_time)と呼ばれることもあり、1970 年 1 月 1 日午前 0 時 (UTC) からの秒数を表します。
AWS CLI バージョン 2 はデフォルトで、すべての***レスポンス***の DateTime 値を ISO 8601 形式に変換します。
`cli\$1timestamp\$1format` ファイル設定を使用して、タイプスタンプ形式を設定できます。
## リスト
スペースで区切られた 1 つ以上の文字列。文字列項目にスペースがある場合は、その項目を引用符で囲む必要があります。予期しない結果を避けるため。お使いの端末の[引用のルール](cli-usage-parameters-quoting-strings.md)を遵守してください。
```
$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium
```
## ブール値
オプションをオンまたはオフにするバイナリフラグです。例えば、`ec2 describe-spot-price-history` にはブール型の `--dry-run` パラメータがあり、このパラメータが指定されると、クエリを実際に実行することなくサービスのクエリを検証します。
```
$ aws ec2 describe-spot-price-history --dry-run
```
出力にはコマンドが正しい形式だったかどうかが示されます。このコマンドには、`--no-dry-run` バージョンのパラメータも含まれ、これを使用して、コマンドを通常どおりに実行することを明示的に示すことができます。これは、デフォルトの動作であるため、含める必要はありません。
## 整数
符号なしの整数。
```
$ aws ec2 describe-spot-price-history --max-items 5
```
## バイナリ/blob (バイナリラージオブジェクト) とストリーミング blob
AWS CLI では、バイナリ値を文字列としてコマンドラインで直接渡すことができます。blob には 2 つのタイプがあります。
+ [blob](#parameter-type-blob)
+ [ストリーミング blob](#parameter-type-streaming-blob)
### blob
タイプ `blob` で、パラメータに値を渡すには、`fileb://` プレフィックスを使用してバイナリデータを含むローカルファイルへのパスを指定する必要があります。`fileb://` プレフィックスを使用して参照されるファイルは、常に、エンコードされていない raw バイナリとして扱われます。指定されたパスは、現在の作業ディレクトリに対する相対パスとして解釈されます。例えば、`--plaintext` の `aws kms encrypt` パラメータは blob です。
```
$ aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
**注記**
下位互換性を保つため、`file://` プレフィックスを使用できます。ファイル設定 `cli\$1binary\$1format` または `--cli-binary-format` コマンドラインオプションに応じて、次の 2 つの形式が使用されます。
AWS CLI バージョン 2 のデフォルト。設定の値が `base64` の場合、`file://` プレフィックスを使用して参照されるファイルは、base64 でエンコードされたテキストとして扱われます。
AWS CLI バージョン 1 のデフォルト。設定の値が `raw-in-base64-out` の場合、`file://` プレフィックスを使用して参照されるファイルはテキストとして読み取られます。AWS CLI は、これをバイナリにエンコードしようとします。
詳細については、ファイル設定 `cli\$1binary\$1format` または `--cli-binary-format` コマンドラインオプションを参照してください。
### ストリーミング blob
`aws cloudsearchdomain upload-documents` などのストリーミング blob はプレフィックスを使用しません。代わりに、ストリーミング blob パラメータは直接ファイルパスを使用してフォーマットされます。次の例では、`aws cloudsearchdomain upload-documents` コマンドに直接ファイルパス `document-batch.json` を使用しています。
```
$ aws cloudsearchdomain upload-documents \
--endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \
--content-type application/json \
--documents document-batch.json
```
## マップ
JSON または CLI の[短縮構文](cli-usage-shorthand.md)を使用して指定されたキーと値のペアのセット。次の JSON の例では、マップパラメータ `--key`を使用して、* my-table *という名前の Amazon DynamoDB テーブルから項目を読み取ります。パラメータは、ネストされた JSON 構造の数値 *1* で *id* という名前のプライマリキーを指定します。
コマンドラインでより高度な JSON を使用するには、`jq` のようなコマンドライン JSON プロセッサを使用して JSON 文字列を作成することを検討してください。`jq` の詳細については、*GitHub* の [jq repository](http://stedolan.github.io/jq/) を参照してください。
```
$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}'
{
"Item": {
"name": {
"S": "John"
},
"id": {
"N": "1"
}
}
}
```
## ドキュメント
**注記**
[短縮構文](cli-usage-shorthand.md)は、ドキュメントタイプと互換性がありません。
ドキュメントタイプは、文字列内に JSON を埋め込む必要なく、データを送信するために使用されます。ドキュメントタイプによってサービスが任意のスキーマを提供することで、より柔軟なデータ型を使用できます。
これにより、値をエスケープすることなく JSON データを送信できます。例えば、次のようにエスケープされた JSON 入力の代わりに使用します。
```
{"document": "{\"key\":true}"}
```
次のドキュメントタイプが使用できます。
```
{"document": {"key": true}}
```
### ドキュメントタイプに対し有効な値
ドキュメントタイプは柔軟な性質を持っているため、有効な値のタイプは複数あります。有効な値には次のようなものがあります。
**String**
```
--option '"value"'
```
**Number**
```
--option 123
--option 123.456
```
**ブール値**
```
--option true
```
**Null**
```
--option null
```
**配列**
```
--option '["value1", "value2", "value3"]'
--option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]'
```
**オブジェクト**
```
--option '{"key": "value"}'
--option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}'
```
# Using quotation marks and literals with strings in the AWS CLI
AWS CLI では、主に、一重引用符と二重引用符の使用方法が 2 つあります。
+ [空白を含む文字列を引用符で囲む](#cli-usage-parameters-quoting-strings-around)
+ [文字列内での引用符の使用](#cli-usage-parameters-quoting-strings-containing)
## 空白を含む文字列を引用符で囲む
コマンドラインでパラメータ名とその値はスペースで区切ります。文字列値にスペースが埋め込まれている場合は、文字列全体を引用符で囲むことで、AWS CLI によってスペースが値と次のパラメータ名との区切りとして誤って解釈されないようにする必要があります。使用する引用符のタイプは、AWS CLI を実行しているオペレーティングシステムによって異なります。
------
#### [ Linux and macOS ]
一重引用符 `' '` を使用します。
```
$ aws ec2 create-key-pair --key-name 'my key pair'
```
引用符の使用方法の詳細については、使用するシェルのユーザードキュメントを参照してください。
------
#### [ PowerShell ]
**一重引用符 (推奨)**
一重引用符 `' '` は `verbatim` 文字列と呼ばれます。文字列は、入力したとおりにコマンドに渡されるため、PowerShell 変数は通過しません。
```
PS C:\> aws ec2 create-key-pair --key-name 'my key pair'
```
**二重引用符**
二重引用符 `" "` は `expandable` 文字列と呼ばれます。変数は拡張可能な文字列で渡すことができます。
```
PS C:\> aws ec2 create-key-pair --key-name "my key pair"
```
引用符の使用方法の詳細については、*Microsoft PowerShell ドキュメント*の「[About Quoting Rules](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7)」を参照してください。
------
#### [ Windows command prompt ]
二重引用符 `" "` を使用します。
```
C:\> aws ec2 create-key-pair --key-name "my key pair"
```
------
オプションとして、パラメータ名と値をスペースの代わりに等号 `=` で区切ることができます。通常、これはパラメータの値がハイフンで始まる場合にのみ必要です。
```
$ aws ec2 delete-key-pair --key-name=-mykey
```
## 文字列内での引用符の使用
文字列に引用符が含まれている場合があり、シェルが正しく動作するためには、引用符のエスケープが必要になることがあります。パラメータ値の一般的なタイプの 1 つとして JSON 文字列があります。JSON 構造内の各要素の名前と値の前後にスペースと二重引用符 `" "` が含まれているため、これは複雑です。コマンドラインで JSON 形式のパラメータを入力する方法はオペレーティングシステムによって異なります。
コマンドラインでより高度な JSON を使用するには、`jq` のようなコマンドライン JSON プロセッサを使用して JSON 文字列を作成することを検討してください。`jq` の詳細については、*GitHub* の [jq repository](http://stedolan.github.io/jq/) を参照してください。
------
#### [ Linux and macOS ]
Linux および macOS で文字列を文字どおりに解釈するには、次の例のように、一重引用符 `' '` を使用して JSON データ構造を囲みます。JSON 文字列に埋め込まれた二重引用符は、文字どおり処理されるため、エスケープする必要はありません。JSON は一重引用符で囲まれているため、文字列内の一重引用符はエスケープする必要があります。このためには、通常は一重引用符 `\'` の前にバックスラッシュを使用します。
```
$ aws ec2 run-instances \
--image-id ami-12345678 \
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
引用符の使用方法の詳細については、使用するシェルのユーザードキュメントを参照してください。
------
#### [ PowerShell ]
一重引用符 `' '` または二重引用符 `" "` を使用します。
**一重引用符 (推奨)**
一重引用符 `' '` は `verbatim` 文字列と呼ばれます。文字列は、入力したとおりにコマンドに渡されるため、PowerShell 変数は通過しません。
JSON データ構造には二重引用符が含まれているため、**一重**引用符 `' '` で囲むことをお勧めします。**一重**引用符を使用する場合は、JSON 文字列に埋め込まれた**二重**引用符をエスケープする必要はありません。ただし、JSON 構造内では、各**一重**引用符をバックティック ``` でエスケープする必要があります。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
**二重引用符**
二重引用符 `" "` は `expandable` 文字列と呼ばれます。変数は拡張可能な文字列で渡すことができます。
**二重**引用符を使用する場合は、JSON 文字列に埋め込まれた **一重**引用符をエスケープする必要はありません。ただし、次の例のように、JSON 構造内で各**二重**引用符をバックティック ``` でエスケープする必要があります。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`"DeviceName`":`"/dev/sdb`",`"Ebs`":{`"VolumeSize`":20,`"DeleteOnTermination`":false,`"VolumeType`":`"standard`"}}]"
```
引用符の使用方法の詳細については、*Microsoft PowerShell ドキュメント*の「[About Quoting Rules](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7)」を参照してください。
**警告**
PowerShell は AWS CLI にコマンドを送信する前に、コマンドが一般的な PowerShell と `CommandLineToArgvW` 引用ルールのどちらを使用して解釈されるかを判断します。PowerShell が `CommandLineToArgvW` を使用して処理する場合は、バックスラッシュ `\` で文字をエスケープする必要があります。
PowerShell の`CommandLineToArgvW` 詳細については、[ マイクロソフトドキュメントブログの](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833)「*Microsoft DevBlogs* [の CommandLineToArgvW による引用符とバックスラッシュの奇妙な扱いの理由](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way)」を参照してください。*コマンドライン引数を間違った方法で引用する人々*、[ および Microsoft Docs ](https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw#remarks)の *CommandLineToArgvW 関数を参照してください * 。
**一重引用符**
一重引用符 `' '` は `verbatim` 文字列と呼ばれます。文字列は、入力したとおりにコマンドに渡されるため、PowerShell 変数は通過しません。バックスラッシュ `\` で文字をエスケープします。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]'
```
**二重引用符**
二重引用符 `" "` は `expandable` 文字列と呼ばれます。変数は `expandable` 文字列で渡すことができます。二重引用符で囲まれた文字列の場合、バックティックだけを使用するのではなく、引用符ごとに *`\$1* を使用して 2 回エスケープする必要があります。バックティックはバックスラッシュをエスケープし、バックスラッシュは `CommandLineToArgvW` プロセスのエスケープ文字として使用されます。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]"
```
**Blobs (推奨)**
JSON データ入力の PowerShell 引用ルールをバイパスするには、BLOB を使用して JSON データを AWS CLI に直接渡します。BLOB の詳細については、「[blob](cli-usage-parameters-types.md#parameter-type-blob)」を参照してください。
------
#### [ Windows command prompt ]
Windows コマンドプロンプトでは、JSON データ構造を二重引用符 `" "` で囲む必要があります。また、コマンドプロセッサによって、JSON に埋め込まれた二重引用符が誤って解釈されないようにするには、以下の例のように、JSON データ構造内の各二重引用符 `\` をエスケープする (バックスラッシュ `"` 文字で始める) 必要もあります。
```
C:\> aws ec2 run-instances ^
--image-id ami-12345678 ^
--block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]"
```
最も外側の二重引用符のみエスケープしません。
------
# AWS CLI でのファイルからのパラメータの読み込み
一部のパラメータでは、AWS CLI がデータをロードするファイル名を引数として期待します。他のパラメータを使用すると、コマンドラインで入力するテキストまたはファイルから読み取るテキストとしてパラメータ値を指定できます。ファイルが必須であるか省略可能であるかに関係なく、AWS CLI がファイルを理解できるように、ファイルを正しくエンコードする必要があります。ファイルのエンコーディングは、読み取りシステムのデフォルトロケールと一致する必要があります。これは、Python の `locale.getpreferredencoding()` メソッドを使用して判断できます。
この方法は 1 つのファイルで 1 つのパラメータを読み込む場合に使用します。1 つのファイルで複数のパラメータを読み込む方法については、「[AWS CLI skeletons and input files in the AWS CLI](cli-usage-skeleton.md)」を参照してください。
**注記**
デフォルトでは、Windows PowerShell はテキストを UTF-16 として出力します。これは、JSON ファイルおよび多くの Linux システムで使用されている UTF-8 エンコードと競合します。`-Encoding ascii` が結果として得られるファイルを読み取ることができるように、PowerShell `Out-File` コマンドで AWS CLI を使用することをお勧めします。
**Topics**
+ [ファイルからパラメータを読み込む方法](#cli-usage-parameters-file-how)
+ [バイナリファイル](#cli-usage-parameters-file-binary)
+ [短縮構文の値としてファイルを読み込む](#cli-usage-parameters-file-shorthand)
## ファイルからパラメータを読み込む方法
場合によっては、コマンドラインパラメータ値としてすべてを入力することを試みる代わりに、ファイルからパラメータ値をロードすることが便利なことがあります (パラメータが複雑な JSON 文字列の場合など)。値を含むファイルを指定するには、次の形式でファイル URL を指定します。
```
file://complete/path/to/file
```
+ 最初の 2 つのスラッシュ「/」文字は仕様の一部です。必要なパスが「/」で始まる場合、結果は 3 つのスラッシュ文字 `file:///folder/file` になります。
+ この URI は、実際のパラメータコンテンツが含まれているファイルへのパスを示します。
+ スペースまたは特殊文字を含むファイルを使用する場合は、お使いの端末の[引用符とエスケープのルール](cli-usage-parameters-quoting-strings.md)に従ってください。
次の例のファイルパスは、現在の作業ディレクトリに対する相対値として解釈されます。
------
#### [ Linux or macOS ]
```
// Read from a file in the current directory
$ aws ec2 describe-instances --filters file://filter.json
// Read from a file in /tmp
$ aws ec2 describe-instances --filters file:///tmp/filter.json
// Read from a file with a filename with whitespaces
$ aws ec2 describe-instances --filters 'file://filter content.json'
```
------
#### [ Windows command prompt ]
```
// Read from a file in C:\temp
C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json
// Read from a file with a filename with whitespaces
C:\> aws ec2 describe-instances --filters "file://C:\temp\filter content.json"
```
------
`file://` プレフィックスオプションは、「`~/`」、「`./`」、および「`../`」など、Unix 形式の拡張子をサポートしています。Windows では、「`~/`」式は、`%USERPROFILE%` 環境変数に格納されているユーザーディレクトリに展開されます。例えば、Windows 10 では、一般にユーザーディレクトリは `%USERPROFILE%` にあります。
別の JSON ドキュメントの値として埋め込まれている JSON ドキュメントもエスケープする必要があります。
```
$ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json
```
**attributes.json**
```
{
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"
}
```
## バイナリファイル
バイナリデータをパラメータとして取るコマンドでは、`fileb://` プレフィックスを使用して、データがバイナリコンテンツであることを指定します。バイナリデータを受け入れるコマンドは次のとおりです。
+ **`aws ec2 run-instances:`**`--user-data`パラメータ
+ **`aws s3api put-object:`**`--sse-customer-key`パラメータ
+ **`aws kms decrypt:`**`--ciphertext-blob`パラメータ
次の例では、Linux コマンドラインツールを使用してバイナリ 256 ビット AES キーを生成し、Amazon S3 に渡して、アップロードされたファイルをサーバー側で暗号化します。
```
$ dd if=/dev/urandom bs=1 count=32 > sse.key
32+0 records in
32+0 records out
32 bytes (32 B) copied, 0.000164441 s, 195 kB/s
$ aws s3api put-object \
--bucket amzn-s3-demo-bucket \
--key test.txt \
--body test.txt \
--sse-customer-key fileb://sse.key \
--sse-customer-algorithm AES256
{
"SSECustomerKeyMD5": "iVg8oWa8sy714+FjtesrJg==",
"SSECustomerAlgorithm": "AES256",
"ETag": "\"a6118e84b76cf98bf04bbe14b6045c6c\""
}
```
JSON 形式のパラメータを含むファイルを参照する別の例については、[ユーザーへの IAM 管理ポリシーのアタッチ](cli-services-iam.md#cli-services-iam-policy) をご参照ください。
## 短縮構文の値としてファイルを読み込む
短縮構文を使用する場合、値が大きいときや複雑なときは、値をファイルとして読み込む方が簡単なことがよくあります。ファイルを短縮構文の値として読み込む場合、形式が少し変わります。`key=value` で、`=` 演算子の代わりに `@=` 演算子を使用します。`@=` は AWS CLI に対して、その値を文字列ではなくファイルパスとして解釈するように指示します。次の例では、キーと値のペアを使用してファイルを読み込む方法を示しています。
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
次の例では、`aws rolesanywhere create-trust-anchor` コマンドで証明書ファイルを読み込む方法を示しています。
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
短縮構文の詳細については、「[Using shorthand syntax in the AWS CLI](cli-usage-shorthand.md)」を参照してください。
# AWS CLI skeletons and input files in the AWS CLI
ほとんどの AWS CLI コマンドは、ファイルからのパラメータ入力のインポートに対応しています。これらのテンプレートは `generate-cli-skeleton` オプションを使用して生成し、`--cli-input-json` および `--cli-input-yaml` パラメータを使用してインポートできます。
**Topics**
+ [AWS CLI スケルトンと入力ファイルについて](#cli-usage-skeleton-about)
+ [コマンドスケルトンを生成してインポートする](#cli-usage-skeleton-generate)
+ [入力ファイルとコマンドラインパラメータの組み合わせ](#cli-usage-skeleton-combine)
## AWS CLI スケルトンと入力ファイルについて
ほとんどの AWS Command Line Interface (AWS CLI) コマンドは、`--cli-input-json` および `--cli-input-yaml` パラメータを使用してファイルからパラメータ入力をインポートする機能をサポートしています。
これらの同じコマンドは、`--generate-cli-skeleton` パラメータを使用して、JSON または YAML 形式のファイルを生成します。このファイルには、編集および入力できるすべてのパラメータが含まれています。その後、入力済みのファイルを `--cli-input-json` または `--cli-input-yaml` パラメータで指定してこのコマンドを実行できます。
**重要**
[`aws s3` コマンド](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) などのカスタム AWS CLI コマンドは、このトピックで説明している `--generate-cli-skeleton` または `--cli-input-json` および `--cli-input-yaml` パラメータをサポートしていません。特定のコマンドがこれらのパラメータをサポートしているかどうかを確認するには、使用するコマンドに対して [`help` コマンド](cli-usage-help.md#cli-usage-help-command)を実行するか、[AWS CLI バージョン 2 リファレンスガイド](https://docs.aws.amazon.com/cli/latest/reference/index.html)を参照してください。
`--generate-cli-skeleton` は、カスタマイズしてコマンドの入力として使用できるパラメータテンプレートを生成して表示します。生成されるテンプレートには、そのコマンドによってサポートされているすべてのパラメータが含まれています。
`--generate-cli-skeleton` パラメータには、次のいずれかの値を指定できます。
+ `input` - 生成されたテンプレートには、JSON 形式の入力パラメータがすべて含まれます。これは、デフォルト値です。
+ `yaml-input` - 生成されたテンプレートには、YAML 形式の入力パラメータがすべて含まれます。
+ `output` - 生成されたテンプレートには、JSON 形式の出力パラメータがすべて含まれます。現在、YAML 形式で出力パラメータを要求することはできません。
AWS CLI は基本的にサービスの API の「ラッパー」であるため、スケルトンファイルは、すべてのパラメータを、基になる API パラメータ名で参照することを想定しています。このパラメータ名は AWS CLI のものとは異なることがあります。例えば、AWS CLI という名前の `user-name` パラメータは、AWS という名前の `UserName` のサービスの API パラメータにマップされる場合があります (大文字小文字が変更されダッシュがないことに注意)。エラーを回避するために、`--generate-cli-skeleton` オプションを使用して「正しい」パラメータ名でテンプレートを生成することをお勧めします。サービスの API リファレンスガイドを参照して、使用可能なパラメータ名を確認できます。テンプレートから、値を指定しない必須でないパラメータを削除できます。
例えば、次のコマンドを実行すると、Amazon Elastic Compute Cloud (Amazon EC2) コマンド**run-instances**のパラメータテンプレートが生成されます 。
------
#### [ JSON ]
次の例は、`input` パラメータのデフォルト値 (`--generate-cli-skeleton`) を使用して JSON でフォーマットされたテンプレートを生成する方法を示しています。
```
$ aws ec2 run-instances --generate-cli-skeleton
```
```
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
```
------
#### [ YAML ]
次の例は、`yaml-input` パラメータの値 (`--generate-cli-skeleton`) を使用して YAML でフォーマットされたテンプレートを生成する方法を示しています。
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input
```
```
BlockDeviceMappings: # The block device mapping entries.
- DeviceName: '' # The device name (for example, /dev/sdh or xvdh).
VirtualName: '' # The virtual device name (ephemeralN).
Ebs: # Parameters used to automatically set up Amazon EBS volumes when the instance is launched.
DeleteOnTermination: true # Indicates whether the EBS volume is deleted on instance termination.
Iops: 0 # The number of I/O operations per second (IOPS) that the volume supports.
SnapshotId: '' # The ID of the snapshot.
VolumeSize: 0 # The size of the volume, in GiB.
VolumeType: st1 # The volume type. Valid values are: standard, io1, gp2, sc1, st1.
Encrypted: true # Indicates whether the encryption state of an EBS volume is changed while being restored from a backing snapshot.
KmsKeyId: '' # Identifier (key ID, key alias, ID ARN, or alias ARN) for a customer managed KMS key under which the EBS volume is encrypted.
NoDevice: '' # Suppresses the specified device included in the block device mapping of the AMI.
ImageId: '' # The ID of the AMI.
InstanceType: c4.4xlarge # The instance type. Valid values are: t1.micro, t2.nano, t2.micro, t2.small, t2.medium, t2.large, t2.xlarge, t2.2xlarge, t3.nano, t3.micro, t3.small, t3.medium, t3.large, t3.xlarge, t3.2xlarge, t3a.nano, t3a.micro, t3a.small, t3a.medium, t3a.large, t3a.xlarge, t3a.2xlarge, m1.small, m1.medium, m1.large, m1.xlarge, m3.medium, m3.large, m3.xlarge, m3.2xlarge, m4.large, m4.xlarge, m4.2xlarge, m4.4xlarge, m4.10xlarge, m4.16xlarge, m2.xlarge, m2.2xlarge, m2.4xlarge, cr1.8xlarge, r3.large, r3.xlarge, r3.2xlarge, r3.4xlarge, r3.8xlarge, r4.large, r4.xlarge, r4.2xlarge, r4.4xlarge, r4.8xlarge, r4.16xlarge, r5.large, r5.xlarge, r5.2xlarge, r5.4xlarge, r5.8xlarge, r5.12xlarge, r5.16xlarge, r5.24xlarge, r5.metal, r5a.large, r5a.xlarge, r5a.2xlarge, r5a.4xlarge, r5a.8xlarge, r5a.12xlarge, r5a.16xlarge, r5a.24xlarge, r5d.large, r5d.xlarge, r5d.2xlarge, r5d.4xlarge, r5d.8xlarge, r5d.12xlarge, r5d.16xlarge, r5d.24xlarge, r5d.metal, r5ad.large, r5ad.xlarge, r5ad.2xlarge, r5ad.4xlarge, r5ad.8xlarge, r5ad.12xlarge, r5ad.16xlarge, r5ad.24xlarge, x1.16xlarge, x1.32xlarge, x1e.xlarge, x1e.2xlarge, x1e.4xlarge, x1e.8xlarge, x1e.16xlarge, x1e.32xlarge, i2.xlarge, i2.2xlarge, i2.4xlarge, i2.8xlarge, i3.large, i3.xlarge, i3.2xlarge, i3.4xlarge, i3.8xlarge, i3.16xlarge, i3.metal, i3en.large, i3en.xlarge, i3en.2xlarge, i3en.3xlarge, i3en.6xlarge, i3en.12xlarge, i3en.24xlarge, i3en.metal, hi1.4xlarge, hs1.8xlarge, c1.medium, c1.xlarge, c3.large, c3.xlarge, c3.2xlarge, c3.4xlarge, c3.8xlarge, c4.large, c4.xlarge, c4.2xlarge, c4.4xlarge, c4.8xlarge, c5.large, c5.xlarge, c5.2xlarge, c5.4xlarge, c5.9xlarge, c5.12xlarge, c5.18xlarge, c5.24xlarge, c5.metal, c5d.large, c5d.xlarge, c5d.2xlarge, c5d.4xlarge, c5d.9xlarge, c5d.18xlarge, c5n.large, c5n.xlarge, c5n.2xlarge, c5n.4xlarge, c5n.9xlarge, c5n.18xlarge, cc1.4xlarge, cc2.8xlarge, g2.2xlarge, g2.8xlarge, g3.4xlarge, g3.8xlarge, g3.16xlarge, g3s.xlarge, g4dn.xlarge, g4dn.2xlarge, g4dn.4xlarge, g4dn.8xlarge, g4dn.12xlarge, g4dn.16xlarge, cg1.4xlarge, p2.xlarge, p2.8xlarge, p2.16xlarge, p3.2xlarge, p3.8xlarge, p3.16xlarge, p3dn.24xlarge, d2.xlarge, d2.2xlarge, d2.4xlarge, d2.8xlarge, f1.2xlarge, f1.4xlarge, f1.16xlarge, m5.large, m5.xlarge, m5.2xlarge, m5.4xlarge, m5.8xlarge, m5.12xlarge, m5.16xlarge, m5.24xlarge, m5.metal, m5a.large, m5a.xlarge, m5a.2xlarge, m5a.4xlarge, m5a.8xlarge, m5a.12xlarge, m5a.16xlarge, m5a.24xlarge, m5d.large, m5d.xlarge, m5d.2xlarge, m5d.4xlarge, m5d.8xlarge, m5d.12xlarge, m5d.16xlarge, m5d.24xlarge, m5d.metal, m5ad.large, m5ad.xlarge, m5ad.2xlarge, m5ad.4xlarge, m5ad.8xlarge, m5ad.12xlarge, m5ad.16xlarge, m5ad.24xlarge, h1.2xlarge, h1.4xlarge, h1.8xlarge, h1.16xlarge, z1d.large, z1d.xlarge, z1d.2xlarge, z1d.3xlarge, z1d.6xlarge, z1d.12xlarge, z1d.metal, u-6tb1.metal, u-9tb1.metal, u-12tb1.metal, u-18tb1.metal, u-24tb1.metal, a1.medium, a1.large, a1.xlarge, a1.2xlarge, a1.4xlarge, a1.metal, m5dn.large, m5dn.xlarge, m5dn.2xlarge, m5dn.4xlarge, m5dn.8xlarge, m5dn.12xlarge, m5dn.16xlarge, m5dn.24xlarge, m5n.large, m5n.xlarge, m5n.2xlarge, m5n.4xlarge, m5n.8xlarge, m5n.12xlarge, m5n.16xlarge, m5n.24xlarge, r5dn.large, r5dn.xlarge, r5dn.2xlarge, r5dn.4xlarge, r5dn.8xlarge, r5dn.12xlarge, r5dn.16xlarge, r5dn.24xlarge, r5n.large, r5n.xlarge, r5n.2xlarge, r5n.4xlarge, r5n.8xlarge, r5n.12xlarge, r5n.16xlarge, r5n.24xlarge.
Ipv6AddressCount: 0 # [EC2-VPC] The number of IPv6 addresses to associate with the primary network interface.
Ipv6Addresses: # [EC2-VPC] The IPv6 addresses from the range of the subnet to associate with the primary network interface.
- Ipv6Address: '' # The IPv6 address.
KernelId: '' # The ID of the kernel.
KeyName: '' # The name of the key pair.
MaxCount: 0 # [REQUIRED] The maximum number of instances to launch.
MinCount: 0 # [REQUIRED] The minimum number of instances to launch.
Monitoring: # Specifies whether detailed monitoring is enabled for the instance.
Enabled: true # [REQUIRED] Indicates whether detailed monitoring is enabled.
Placement: # The placement for the instance.
AvailabilityZone: '' # The Availability Zone of the instance.
Affinity: '' # The affinity setting for the instance on the Dedicated Host.
GroupName: '' # The name of the placement group the instance is in.
PartitionNumber: 0 # The number of the partition the instance is in.
HostId: '' # The ID of the Dedicated Host on which the instance resides.
Tenancy: dedicated # The tenancy of the instance (if the instance is running in a VPC). Valid values are: default, dedicated, host.
SpreadDomain: '' # Reserved for future use.
RamdiskId: '' # The ID of the RAM disk to select.
SecurityGroupIds: # The IDs of the security groups.
- ''
SecurityGroups: # [default VPC] The names of the security groups.
- ''
SubnetId: '' # [EC2-VPC] The ID of the subnet to launch the instance into.
UserData: '' # The user data to make available to the instance.
AdditionalInfo: '' # Reserved.
ClientToken: '' # Unique, case-sensitive identifier you provide to ensure the idempotency of the request.
DisableApiTermination: true # If you set this parameter to true, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can.
DryRun: true # Checks whether you have the required permissions for the action, without actually making the request, and provides an error response.
EbsOptimized: true # Indicates whether the instance is optimized for Amazon EBS I/O.
IamInstanceProfile: # The IAM instance profile.
Arn: '' # The Amazon Resource Name (ARN) of the instance profile.
Name: '' # The name of the instance profile.
InstanceInitiatedShutdownBehavior: stop # Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown). Valid values are: stop, terminate.
NetworkInterfaces: # The network interfaces to associate with the instance.
- AssociatePublicIpAddress: true # Indicates whether to assign a public IPv4 address to an instance you launch in a VPC.
DeleteOnTermination: true # If set to true, the interface is deleted when the instance is terminated.
Description: '' # The description of the network interface.
DeviceIndex: 0 # The position of the network interface in the attachment order.
Groups: # The IDs of the security groups for the network interface.
- ''
Ipv6AddressCount: 0 # A number of IPv6 addresses to assign to the network interface.
Ipv6Addresses: # One or more IPv6 addresses to assign to the network interface.
- Ipv6Address: '' # The IPv6 address.
NetworkInterfaceId: '' # The ID of the network interface.
PrivateIpAddress: '' # The private IPv4 address of the network interface.
PrivateIpAddresses: # One or more private IPv4 addresses to assign to the network interface.
- Primary: true # Indicates whether the private IPv4 address is the primary private IPv4 address.
PrivateIpAddress: '' # The private IPv4 addresses.
SecondaryPrivateIpAddressCount: 0 # The number of secondary private IPv4 addresses.
SubnetId: '' # The ID of the subnet associated with the network interface.
InterfaceType: '' # The type of network interface.
PrivateIpAddress: '' # [EC2-VPC] The primary IPv4 address.
ElasticGpuSpecification: # An elastic GPU to associate with the instance.
- Type: '' # [REQUIRED] The type of Elastic Graphics accelerator.
ElasticInferenceAccelerators: # An elastic inference accelerator to associate with the instance.
- Type: '' # [REQUIRED] The type of elastic inference accelerator.
TagSpecifications: # The tags to apply to the resources during launch.
- ResourceType: network-interface # The type of resource to tag. Valid values are: client-vpn-endpoint, customer-gateway, dedicated-host, dhcp-options, elastic-ip, fleet, fpga-image, host-reservation, image, instance, internet-gateway, launch-template, natgateway, network-acl, network-interface, reserved-instances, route-table, security-group, snapshot, spot-instances-request, subnet, traffic-mirror-filter, traffic-mirror-session, traffic-mirror-target, transit-gateway, transit-gateway-attachment, transit-gateway-route-table, volume, vpc, vpc-peering-connection, vpn-connection, vpn-gateway.
Tags: # The tags to apply to the resource.
- Key: '' # The key of the tag.
Value: '' # The value of the tag.
LaunchTemplate: # The launch template to use to launch the instances.
LaunchTemplateId: '' # The ID of the launch template.
LaunchTemplateName: '' # The name of the launch template.
Version: '' # The version number of the launch template.
InstanceMarketOptions: # The market (purchasing) option for the instances.
MarketType: spot # The market type. Valid values are: spot.
SpotOptions: # The options for Spot Instances.
MaxPrice: '' # The maximum hourly price you're willing to pay for the Spot Instances.
SpotInstanceType: one-time # The Spot Instance request type. Valid values are: one-time, persistent.
BlockDurationMinutes: 0 # The required duration for the Spot Instances (also known as Spot blocks), in minutes.
ValidUntil: 1970-01-01 00:00:00 # The end date of the request.
InstanceInterruptionBehavior: terminate # The behavior when a Spot Instance is interrupted. Valid values are: hibernate, stop, terminate.
CreditSpecification: # The credit option for CPU usage of the T2 or T3 instance.
CpuCredits: '' # [REQUIRED] The credit option for CPU usage of a T2 or T3 instance.
CpuOptions: # The CPU options for the instance.
CoreCount: 0 # The number of CPU cores for the instance.
ThreadsPerCore: 0 # The number of threads per CPU core.
CapacityReservationSpecification: # Information about the Capacity Reservation targeting option.
CapacityReservationPreference: none # Indicates the instance's Capacity Reservation preferences. Valid values are: open, none.
CapacityReservationTarget: # Information about the target Capacity Reservation.
CapacityReservationId: '' # The ID of the Capacity Reservation.
HibernationOptions: # Indicates whether an instance is enabled for hibernation.
Configured: true # If you set this parameter to true, your instance is enabled for hibernation.
LicenseSpecifications: # The license configurations.
- LicenseConfigurationArn: '' # The Amazon Resource Name (ARN) of the license configuration.
```
------
## コマンドスケルトンを生成してインポートする
**パラメータスケルトンファイルを生成して使用するには**
1. `--generate-cli-skeleton` パラメータを指定してコマンドを実行して JSON または YAML のいずれかを生成し、出力を保存用ファイルに送ります。
------
#### [ JSON ]
```
$ aws ec2 run-instances --generate-cli-skeleton input > ec2runinst.json
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --generate-cli-skeleton yaml-input > ec2runinst.yaml
```
------
1. テキストエディタでパラメータスケルトンファイルを開き、不要なパラメータを削除します。例えば、テンプレートを次のように削除できます。不要な要素を削除した後、ファイルが有効な JSON または YAML であることを確認します。
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "",
"KeyName": "",
"SecurityGroups": [
""
],
"InstanceType": "",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: ''
KeyName: ''
SecurityGroups:
- ''
InstanceType:
Monitoring:
Enabled: true
```
------
この例では、Amazon EC2 ドライラン機能を使用するには、`DryRun` パラメータを `true` に設定したままにします。この機能を使用すると、実際にリソースを作成または変更することなく、コマンドを安全にテストできます。
1. 残りの値には、シナリオに適した値を入力します。この例では、インスタンスタイプ、キー名、セキュリティグループ、および使用する Amazon マシンイメージ (AMI) の識別子を指定しています。この例では、デフォルトの AWS リージョン リージョンを前提としています。AMI `ami-dfc39aef` は、`us-west-2` リージョンでホストされている 64 ビットの Amazon Linux イメージです。別のリージョンを使用する場合は、[使用する正しい AMI ID を見つける必要があります](https://aws.amazon.com/amazon-linux-ami/)。
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: true
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. `file://` プレフィックスを使用して、完了したテンプレートファイルを `--cli-input-json` または --`cli-input-yaml` パラメータのいずれかに渡すことによって、入力済みパラメータでコマンドを実行します。AWS CLI は、パスを現在の作業ディレクトリからの相対パスとして解釈します。次の例では、AWS CLI は現在の作業ディレクトリ内のファイルを検索します。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
リハーサルのエラーは、JSON または YAML の形式が正しく、パラメータ値が有効であることを示します。出力でその他の問題が報告された場合は、それを修正し、「`Request would have succeeded`」というメッセージが表示されるまで前のステップを繰り返します。
1. これで、`DryRun` パラメータを `false` に設定して、dry run を無効にできます。
------
#### [ JSON ]
```
{
"DryRun": false,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
```
DryRun: false
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
1. コマンドを実行すると、`run-instances` は Amazon EC2 インスタンスを実際に起動し、正常起動によって生成された詳細を表示します。出力の形式は、入力パラメータテンプレートの形式とは別に、`--output` パラメータによって制御されます。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
## 入力ファイルとコマンドラインパラメータの組み合わせ
入力ファイルはすべてのパラメータに使用することも、AWS CLI で指定したパラメータと組み合わせることもできます。この機能を利用すると、繰り返し使用する設定は入力ファイルに保存する一方で、個別の設定はコマンド自体で指定できます。
次の `aws ec2 run-instances` の例では、入力ファイルとパラメータを組み合わせて使用しています。使用する Amazon マシンイメージ (AMI) のインスタンスタイプ、キー名、セキュリティグループ、識別子を指定し、デフォルトの AWS リージョン を前提としています。AMI `ami-dfc39aef` は、`us-west-2` リージョンでホストされている 64 ビットの Amazon Linux イメージです。別のリージョンを使用する場合は、[使用する正しい AMI ID を見つける必要があります](https://aws.amazon.com/amazon-linux-ami/)。
------
#### [ JSON ]
JSON ファイルの内容:
```
{
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
#### [ YAML ]
YAML ファイルの内容:
```
ImageId: 'ami-dfc39aef'
KeyName: 'mykey'
SecurityGroups:
- 'my-sg'
InstanceType: 't2.micro'
Monitoring:
Enabled: true
```
------
次の例では、入力ファイルと `--dry-run` パラメータを組み合わせて使用して、コマンドをドライランし、必要なアクセス許可があるかどうか、ファイルに有効な値が入力されているかどうかを確認します。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
次の例では、同じ入力ファイルを使用しますが、`--no-dry-run` パラメータを使用してコマンドを本番実行しています。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --no-dry-run --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
#### [ YAML ]
```
$ aws ec2 run-instances --cli-input-yaml file://ec2runinst.yaml --no-dry-run --output yaml
```
```
OwnerId: '123456789012'
ReservationId: 'r-d94a2b1',
Groups":
- ''
Instances:
...
```
------
# Using shorthand syntax in the AWS CLI
AWS Command Line Interface (AWS CLI) は、JSON 形式の多くのオプションパラメータを受け入れることができます。ただし、大きな JSON リストや構造体をコマンドラインに入力するのは手間がかかる場合があります。これを簡単にするために、AWS CLI は短縮構文もサポートしているため、完全な JSON 形式を使用するより、オプションパラメータを簡単に表現できます。
**Topics**
+ [キーと値のペアでパラメータを構造化する](#shorthand-structure-parameters)
+ [短縮構文の値としてファイルを読み込む](#shorthand-files)
+ [AWS CLI を使用した短縮構文の使用](#shorthand-list-parameters)
## キーと値のペアでパラメータを構造化する
AWS CLI の短縮構文を利用すると、ユーザーがフラットなパラメータ (ネストされていない構造) に入力するのが容易になります。形式は、キーと値のペアのカンマ区切りリストです。短縮構文は文字列であるため、必ず、お使いのターミナルに適した[引用](cli-usage-parameters-quoting-strings.md)とエスケープの規則を使用してください。
------
#### [ Linux or macOS ]
```
--option key1=value1,key2=value2,key3=value3
```
JSON 形式の次の例と同じになっています。
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
#### [ Windows ]
```
--option "key1=value1,key2=value2,key3=value3"
```
JSON 形式の次の例と同じになっています。
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
それぞれのカンマ区切りのキーと値のペアの間に空白があってはいけません。以下に、Amazon DynamoDB `update-table` コマンドの例を示します。`--provisioned-throughput` オプションは、省略表記で指定されています。
```
$ aws dynamodb update-table \
--provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 \
--table-name MyDDBTable
```
これは、JSON 形式の次の例と同じになっています。
```
$ aws dynamodb update-table \
--provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' \
--table-name MyDDBTable
```
## 短縮構文の値としてファイルを読み込む
値が大きいときや複雑なときは、値として読み込む方が簡単なことがよくあります。ファイルを短縮構文の値として読み込む場合、形式が少し変わります。`key=value` で、`=` 演算子の代わりに `@=` 演算子を使用します。`@=` は AWS CLI に対して、その値を文字列ではなくファイルパスとして解釈するように指示します。短縮構文でファイルを読み込む場合、通常の [AWS CLI ファイル形式ルールが適用](cli-usage-parameters-file.md)されます。次の例では、キーと値のペアを使用してファイルを読み込む方法を示しています。
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
次の例では、`aws rolesanywhere create-trust-anchor` コマンドで証明書ファイルを読み込む方法を示しています。
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
## AWS CLI を使用した短縮構文の使用
リストフォーム内の入力パラメータは、JSON または省略形の 2 つの方法で指定できます。AWS CLI の短縮構文は、数値、文字列、またはネストされていない構造体が含まれるリストを簡単に渡せるように設計されています。
基本的な形式を次に示します。ここで、リストの値は、1 つのスペースで区切られます。
```
--option value1 value2 value3
```
これは、JSON 形式の次の例と同じになっています。
```
--option '[value1,value2,value3]'
```
前述したように、数字のリスト、文字列のリスト、またはネストされていない構造の省略表現のリストを指定できます。Amazon Elastic Compute Cloud (Amazon EC2) の `stop-instances` コマンドの例を次に示します。ここで、`--instance-ids` オプションの入力パラメータ (文字列のリスト) は省略表現で指定されています。
```
$ aws ec2 stop-instances \
--instance-ids i-1486157a i-1286157c i-ec3a7e87
```
これは、JSON 形式の次の例と同じになっています。
```
$ aws ec2 stop-instances \
--instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]'
```
次の例は、Amazon EC2 `create-tags` コマンドを示しています。このコマンドは、`--tags` オプションのネストされていない構造のリストを取得します。`--resources` オプションは、タグを付けるインスタンスの ID を指定します。
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3
```
これは、JSON 形式の次の例と同じになっています。JSON パラメータは、読みやすくするために複数行で記述されます。
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags '[
{"Key": "My1stTag", "Value": "Value1"},
{"Key": "My2ndTag", "Value": "Value2"},
{"Key": "My3rdTag", "Value": "Value3"}
]'
```
# AWS CLI でのコマンドプロンプトの有効化と使用
AWS CLI バージョン 2 では、`aws` コマンドの実行時にコマンド、パラメータ、およびリソースのプロンプトを表示できます。
**Topics**
+ [仕組み](#cli-usage-auto-prompt-about)
+ [自動プロンプト機能](#cli-usage-auto-prompt-features)
+ [自動プロンプトモード](#cli-usage-auto-prompt-modes)
+ [自動プロンプトの設定](#cli-usage-auto-prompt-configure)
## 仕組み
有効にすると、自動プロンプトが **Enter** キーを使用して部分的に入力されたコマンドを完成できるようにします。**Enter** キーを押すと、続けて入力する内容に基づいて、コマンド、パラメータ、およびリソースが提案されます。提案には、左側にコマンド、パラメーター、またはリソースの名前、右側にそれらの説明が記載されます。提案を選択して使用するには、矢印キーを使用して行をハイライト表示してから、**Space** キーを押します。コマンドでの入力が終了したら、**Enter** を押してコマンドを使用します。以下の例は、自動プロンプトから提案されたリストがどのように表示されるかを示しています。
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
## 自動プロンプト機能
自動プロンプトには、以下の便利な機能が含まれています。
**ドキュメントパネル**
現在のコマンドのヘルプドキュメントを提供します。ドキュメントを開くには、**F3** キーを押します。
**コマンド補完**
使用する `aws` コマンドを提案します。リストを表示するには、コマンドを部分的に入力します。以下の例は、`a` の文字で始まるサービスを検索します。
```
$ aws
> aws a
accessanalyzer Access Analyzer
acm AWS Certificate Manager
acm-pca AWS Certificate Manager Private Certificate Authority
alexaforbusiness Alexa For Business
amplify AWS Amplify
```
**パラメータ補完**
コマンドを入力すると、自動プロンプトがパラメータの提案を開始します。パラメータの説明には、値のタイプ、およびパラメータが何であるかの説明が含まれます。必須のパラメータが最初にリストされ、「required」というラベルが付けられます。以下の例は、`aws dynamodb describe-table` に対するパラメータの自動プロンプトリストを示しています。
```
$ aws dynamodb describe-table
> aws dynamodb describe-table
--table-name (required) [string] The name of the table to describe.
--cli-input-json [string] Reads arguments from the JSON string provided. The JSON string follows the format provide...
--cli-input-yaml [string] Reads arguments from the YAML string provided. The YAML string follows the format provide...
--generate-cli-skeleton [string] Prints a JSON skeleton to standard output without sending an API request. If provided wit...
```
**リソース補完**
自動プロンプトは、利用可能な AWS リソースプロパティを使用して AWS API コールを実行し、リソースの値を提案します。これは、パラメータの入力時に、自動プロンプトが使用可能なユーザー所有のリソースを提案することを可能にします。以下の例では、`--table-name` コマンドの `aws dynamodb describe-table` パラメータを入力するときに、自動プロンプトがテーブル名をリストアップします。
```
$ aws dynamodb describe-table
> aws dynamodb describe-table --table-name
Table1
Table2
Table3
```
**短縮構文補完**
短縮構文を使用するパラメータには、自動プロンプトは使用する値を提案します。以下の例では、自動プロンプトが `--placement` コマンドの `aws ec2 run-instances` パラメータに対する短縮構文をリストアップします。
```
$ aws ec2 run-instances
> aws ec2 run-instances --placement
AvailabilityZone= [string] The Availability Zone of the instance. If not specified, an Availability Zone wil...
Affinity= [string] The affinity setting for the instance on the Dedicated Host. This parameter is no...
GroupName= [string] The name of the placement group the instance is in.
PartitionNumber= [integer] The number of the partition the instance is in. Valid only if the placement grou...
```
**ファイル補完**
`aws` コマンドのパラメータを入力するときに、自動入力が `file://` または `fileb://` プレフィックスを使用した後に続くローカルファイル名を提案します。以下の例では、`--item file://` コマンドに `aws ec2 run-instances` を入力した後で、自動プロンプトがローカルファイルを提案します。
```
$ aws ec2 run-instances
> aws ec2 run-instances --item file://
item1.txt
file1.json
file2.json
```
**リージョン補完**
グローバルパラメータの `--region` を使用するときは、自動プロンプトが選択可能なリージョンをリストアップします。以下の例では、`aws dynamodb list-tables` コマンドの `--region` を入力した後で、自動プロンプトがリージョンをアルファベット順に提案します。
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region
af-south-1
ap-east-1
ap-northeast-1
ap-northeast-2
```
**プロファイル補完**
グローバルパラメータの `--profile` を使用するときは、自動プロンプトがプロファイルをリストアップします。以下の例では、`--profile` コマンドに `aws dynamodb list-tables` を入力した後で、自動プロンプトがユーザーのプロファイルを提案します。
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --profile
profile1
profile2
profile3
```
**あいまい検索**
特定の文字セットを含むコマンドと値を補完します。以下の例では、`aws dynamodb list-tables` コマンドに `--region eu` を入力した後で、自動プロンプトが `eu` が含まれるリージョンを提案します。
```
$ aws dynamodb list-tables
> aws dynamodb list-tables --region west
eu-west-1
eu-west-2
eu-west-3
us-west-1
```
**履歴**
自動プロンプトモードで以前に使用したコマンドを表示して実行するには、**CTRL \$1 R** を押します。履歴には以前のコマンドがリストされ、これらは矢印キーを使用して選択できます。以下の例では、自動プロンプトモードの履歴が表示されています。
```
$ aws
> aws
dynamodb list-tables
s3 ls
```
## 自動プロンプトモード
AWS CLI バージョン 2 の自動プロンプトには、設定可能な 2 つのモードがあります。
+ **フルモード:** `aws` パラメータを使用して手動で呼び出すか、永続的に有効化したかにかかわらず、`--cli-auto-prompt` コマンドを実行しようとするたびに自動プロンプトを使用します。これには、完全なコマンドまたは不完全なコマンドを問わず、それらの後で **Enter** キーを押すことが含まれます。
+ **部分モード:** コマンドが不完全であるか、クライアント側の検証エラーのために実行できない場合に自動プロンプトを使用します。このモードは、既存のスクリプトまたはランブックがある場合、あるいはすべてのコマンドに対してプロンプトを表示するのではなく、不慣れなコマンドにのみ自動プロンプトを表示したい場合に特に便利です。
## 自動プロンプトの設定
自動プロンプトを設定するには、次の方法を優先順に使用することができます。
+ **コマンドラインオプション**は、単一のコマンドに対して自動プロンプトを有効化または無効化します。`--cli-auto-prompt` を使用して自動プロンプトを呼び出し、`--no-cli-auto-prompt` を使用して自動プロンプトを無効化してください。
+ **環境変数**では、`aws\$1cli\$1auto\$1prompt` 変数が使用されます。
+ **共有設定ファイル**では、`cli\$1auto\$1prompt` 設定が使用されます。
# 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)」をご参照ください。
### 識別子の値にラベルを追加する
この出力を読みやすくするには、次の構文で複数選択ハッシュを使用します。
**構文**
```
[].{