# 使用 AWS CLI
除[在 AWS CLI 中使用端点](cli-configure-endpoints.md)一节中介绍的详细内容外，本节还概述了 AWS Command Line Interface（AWS CLI）的一般用法、常见功能和可用选项。
本指南深入探讨了编写 AWS CLI 命令的基本方面，包括这些命令的基本结构、格式设置和筛选功能。通过了解这些核心元素，您将能够构建精确针对所需资源和操作的命令，而无需浏览基于 Web 的复杂控制台。
此外，还重点介绍了适用于 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 CLI 用于各种 AWS 服务。
**注意**
默认情况下，AWS CLI 通过在 TCP 端口 443 上使用 HTTPS，将请求发送到 AWS 服务。要成功使用 AWS CLI，您必须能够在该端口上建立出站连接。
**Topics**
+ [在 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)
+ [在 AWS CLI 中控制命令输出](cli-usage-output.md)
+ [AWS CLI 中的命令行返回代码](cli-usage-returncodes.md)
+ [在 AWS CLI 中使用自定义向导运行交互式命令](cli-usage-wizard.md)
+ [在 AWS CLI 中创建和使用别名](cli-usage-alias.md)
+ [排查 AWS CLI 错误](cli-chap-troubleshooting.md)
# 在 AWS CLI 中获取帮助和资源
本主题介绍如何访问 AWS Command Line Interface（AWS CLI）的帮助内容。
**Topics**
+ [内置 AWS CLI 帮助命令](#cli-usage-help-command)
+ [AWS CLI 参考指南](#cli-reference)
+ [API 文档](#api-reference)
+ [错误故障排除](#help-tshoot)
+ [其他帮助](#help-additional)
## 内置 AWS CLI 帮助命令
使用 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`：在终端中打开手册页。
+ `browser`：在默认浏览器中以本地 HTML 文件形式打开手册页。打开默认浏览器时，会在终端上输出一条通知，如果 AWS CLI 无法打开您的浏览器，则会显示一条错误消息。
+ `url`：输出您已安装的 AWS CLI 版本的联机 AWS CLI 参考指南的 URL。采用客户端分页（例如 `AWS_PAGER` 环境变量）的设置。
每个命令的帮助内容分为六个部分：
名称
命令的名称。
```
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` 列表来描述一个或多个实例；`dry-run` 是不接受值的可选布尔标志。要使用布尔标志，请指定其中一个显示的值，在本例中为 `--dry-run` 或 `--no-dry-run`。同样，`--generate-cli-skeleton` 不使用值。如果某个选项的使用存在条件，则在 `OPTIONS` 部分中描述这些条件，或在示例中显示这些条件。
选项
对摘要中显示的每个选项的描述。
```
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 用户**
您可以通过*管道* (\$1) 将 help 命令的输出发送到 `more` 命令以便每次查看一页帮助文件。按空格键或 **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 文档的各部分**
+ **Actions**（操作）– 有关每个操作及其参数（包括对长度或内容以及默认值的约束）的详细信息。它列出了此操作可能发生的错误。每个操作对应于 AWS CLI 中的一个子命令。
+ **Data Types**（数据类型）– 有关命令可能需要作为参数或在响应请求时要返回的结构的详细信息。
+ **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 CLI 支持的AWS服务。
1. 用于指定要执行的操作的*子命令*。
1. 常规 AWS CLI 选项或操作所需的参数。您可以按任意顺序指定这些项，只要它们跟在前三个部分之后。如果多次指定某个排他参数，则仅应用*最后一个值*。
```
$ 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 命令阻止进入后续步骤。
AWS CLI 在命令行上对 `wait` 命令使用多部分结构，各部分必须按如下顺序指定：
1. 对 `aws` 计划的基本调用。
1. 顶级*命令*，这通常对应于 AWS CLI 支持的AWS服务。
1. `wait` 命令。
1. 用于指定要执行的操作的*子命令*。
1. 常规 CLI 选项或操作所需的参数。您可以按任意顺序指定这些项，只要它们跟在前三个部分之后。如果多次指定某个排他参数，则仅应用*最后一个值*。
```
$ aws wait [options and parameters]
```
参数可采用各种类型的输入值，如数字、字符串、列表、映射和 JSON 结构。支持的内容取决于您指定的命令和子命令。
**注意**
并不是所有 AWS 服务都支持 `wait` 命令。请参阅 [AWS CLI 版本 2 参考指南](https://docs.aws.amazon.com/cli/latest/reference/index.html)，了解您的服务是否支持 `wait` 命令。
### 示例
**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 不区分大小写。这意味着，以下两个命令示例对于区分大小写的终端会产生不同的结果，因为它们将 `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)
有时，您需要在包含特殊字符或空格字符的字符串周围使用引号或文字。有关此格式的规则也可能因终端而异。有关在复杂参数周围使用引号的更多信息，请参阅 [在 AWS CLI 中将引号和文本与字符串结合使用](cli-usage-parameters-quoting-strings.md)。
这些主题涵盖最常见的终端格式设置规则。如果您在终端识别参数值时遇到问题，请务必查看本节中的主题，并查看终端文档以了解其特定语法规则。
**Topics**
+ [AWS CLI 中的通用参数类型](cli-usage-parameters-types.md)
+ [在 AWS CLI 中将引号和文本与字符串结合使用](cli-usage-parameters-quoting-strings.md)
+ [在 AWS CLI 中从文件加载参数](cli-usage-parameters-file.md)
+ [在 AWS CLI 中生成 AWS CLI 骨架和输入文件](cli-usage-skeleton.md)
+ [在 AWS CLI 中使用速记语法](cli-usage-shorthand.md)
# AWS CLI 中的通用参数类型
本节介绍一些通用参数类型以及典型的所需格式。
如果您不知道如何设置特定命令的参数格式，请在命令名称后输入 **help** 来查看帮助。每个子命令的帮助均包括一个选项的名称和描述。该选项的参数类型在括号中列出。有关查看帮助的更多信息，请参阅 [在 AWS CLI 中获取帮助和资源](cli-usage-help.md)。
**Topics**
+ [字符串](#parameter-type-string)
+ [Timestamp](#parameter-type-timestamp)
+ [列表](#parameter-type-list)
+ [布尔值](#parameter-type-boolean)
+ [整数](#parameter-type-integer)
+ [二进制/Blob（二进制大型对象）和流式传输 Blob](#parameter-type-blobs)
+ [映射](#parameter-type-map)
+ [文档](#parameter-type-document)
## 字符串
字符串参数可以包含 [ASCII](https://wikipedia.org/wiki/ASCII) 字符集中的字母数字字符、符号和空格。包含空格的字符串必须用引号引起来。建议您不要使用标准空格字符以外的符号或空格，并遵循终端的[引用规则](cli-usage-parameters-quoting-strings.md)，以防止出现意外结果。
一些字符串参数可接受来自文件的二进制数据。有关示例，请参阅[二进制文件](cli-usage-parameters-file.md#cli-usage-parameters-file-binary)。
## Timestamp
时间戳根据 [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 日午夜 (UTC) 以来经历的秒数。
预设情况下，AWS CLI 版本 2 会将所有***响应*** DateTime 值转换为 ISO 8601 格式。
您可以使用 `cli\$1timestamp\$1format` 文件设置来设置时间戳格式。
## 列表
以空格分隔的一个或多个字符串。如果任何字符串项目包含空格，则必须用引号括起该项目。遵循您终端的[引号规则](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：
+ [Blob](#parameter-type-blob)
+ [流式 blob](#parameter-type-streaming-blob)
### Blob
要将值传递给类型为 `blob` 的参数，必须使用 `fileb://` 前缀指定包含二进制数据的本地文件的路径。使用 `fileb://` 前缀引用的文件始终被作为原始未编码二进制文件进行处理。指定的路径被解释为相对于当前工作目录。例如，适用于 `aws kms encrypt` 的 `--plaintext` 参数是一个 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` 命令行选项，可以使用两种格式：
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 示例使用 map 参数 `--key` 从名为 *my-table* 的 Amazon DynamoDB 表中读取项目。此参数在嵌套的 JSON 结构中指定名为 *id* 且数值为 *1* 的主键。
要在命令行中使用更高级的 JSON，请考虑使用 `jq` 等命令行 JSON 处理器来创建 JSON 字符串。有关 `jq` 的更多信息，请参阅 *GitHub* 上的 [jq 存储库](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}}
```
### 文档类型的有效值
由于文档类型本身多种多样，因此存在多个有效值类型。有效值包括：
**字符串**
```
--option '"value"'
```
**数字**
```
--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"}'
```
# 在 AWS CLI 中将引号和文本与字符串结合使用
在 AWS CLI 中使用单引号和双引号主要有两种方式。
+ [在包含空格的字符串周围使用引号](#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'
```
有关使用引号的更多信息，请参阅首选 Shell 的用户文档。
------
#### [ 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 文档* 中的[关于引号规则](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
```
## 在字符串内使用引号
字符串可能包含引号，并且您的 Shell 可能需要对引号进行转义才能让其正常发挥作用。常见的参数值类型之一是 JSON 字符串。这很复杂，因为它在 JSON 结构中的每个元素名称和值周围都包含空格和双引号 `" "`。在命令行中输入 JSON 格式参数的方式因操作系统而异。
要在命令行中使用更高级的 JSON，请考虑使用 `jq` 等命令行 JSON 处理器来创建 JSON 字符串。有关 `jq` 的更多信息，请参阅 *GitHub* 上的 [jq 存储库](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"}}]'
```
有关使用引号的更多信息，请参阅首选 Shell 的用户文档。
------
#### [ 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 文档* 中的[关于引号规则](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` 的更多信息，请参阅 *Microsoft DevBlogs* 上的 [What's up with the strange treatment of quotation marks and backslashes by CommandLineToArgvW](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833)（CommandLineToArgvW 对引号和反斜杠的奇怪处理是怎么回事）、*Microsoft Docs Blog* 中的 [Everyone quotes command line arguments the wrong way](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way)（每个人引用命令行参数的方法都错了）以及 *Microsoft Docs* 上的 [CommandLineToArgvW function](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* 进行两次转义，而不是仅使用反引号。反引号对反斜杠进行转义，然后将反斜杠用作 `CommandLineToArgvW` 流程的转义字符。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]"
```
**Blob（推荐）**
要绕过 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()` 方法来确定这一点。
此方法用于为单个参数加载文件。有关使用单个文件加载多个参数的信息，请参阅[在 AWS CLI 中生成 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
```
+ 前两个斜杠“/”字符是规范的一部分。如果所需的路径以“/”开头，结果为三个斜杠字符：`file:///folder/file`。
+ URL 提供包含实际参数内容的文件的路径。
+ 使用带空格或特殊字符的文件时，请遵循终端的[引用和转义规则](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
```
有关速记语法的更多信息，请参阅[在 AWS CLI 中使用速记语法](cli-usage-shorthand.md)。
# 在 AWS CLI 中生成 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 CLI 命令（例如 [`aws s3` 命令](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html)）不支持本主题中介绍的 `--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 ]
以下示例演示如何使用 `--generate-cli-skeleton` 参数的值 `yaml-input` 生成格式化为 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
```
------
在此示例中，我们将 `DryRun` 参数设置为 `true` 以使用 Amazon EC2 空运行功能。通过此功能，您可以安全地测试命令，而无需实际创建或修改任何资源。
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` 以禁用空运行。
------
#### [ 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` 示例结合使用了输入文件和参数。我们提供要使用的亚马逊机器映像（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:
...
```
------
# 在 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 或速记。使用 AWS CLI 速记语法，可更方便地传入含有数字、字符串或非嵌套结构的列表。
下面显示了基本格式，列表中的值用单个空格分隔。
```
--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` 命令时，您可以让 AWS CLI 版本 2 提示输入命令、参数和资源。
**Topics**
+ [工作原理](#cli-usage-auto-prompt-about)
+ [自动提示功能](#cli-usage-auto-prompt-features)
+ [自动提示模式](#cli-usage-auto-prompt-modes)
+ [配置自动提示](#cli-usage-auto-prompt-configure)
## 工作原理
如果启用，自动提示可让您使用 **Enter** 键完成部分输入的命令。按 **Enter** 键后，根据您继续键入的内容，建议命令、参数和资源。建议在左侧列出了命令、参数或资源的名称，在右侧列出了该命令、参数或资源的说明。要选择并使用建议，请使用箭头键突出显示某个行，然后按**空格**键。输入完命令后，按 **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
```
**参数完成**
键入命令后，自动提示功能会开始建议参数。参数的描述包括值类型以及对参数定义的描述。首先列出必要的参数，并将它们标记为必需。以下示例显示了 `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 来建议资源值。这样就能够在输入参数时自动提示以建议您可能拥有的资源。在以下示例中，在填写 `aws dynamodb describe-table` 命令的 `--table-name` 参数时，自动提示会列出表名称。
```
$ aws dynamodb describe-table
> aws dynamodb describe-table --table-name
Table1
Table2
Table3
```
**速记完成**
对于使用速记语法的参数，自动提示会建议要使用的值。在以下示例中，自动提示列出了 `aws ec2 run-instances` 命令中 `--placement` 参数的速记语法值。
```
$ 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://` 后建议本地文件名。在以下示例中，在为 `aws ec2 run-instances` 命令输入 `--item file://` 后，自动提示会建议使用本地文件。
```
$ 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` 时，自动提示会列出您的配置文件。在以下示例中，在为 `aws dynamodb list-tables` 命令输入 `--profile` 后，自动提示会建议您的配置文件。
```
$ 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 种可以配置的模式：
+ **完全模式：**无论是使用 `--cli-auto-prompt` 参数手动调用 `aws` 命令还是永久启用该命令，每次尝试运行该命令时都会使用自动提示。这包括在完整或不完整的命令之后按 **Enter** 键。
+ **部分模式：**如果命令不完整或由于客户端验证错误而无法运行，则使用自动提示。如果您已有现有脚本、运行手册，或者如果您希望只对于不熟悉的命令收到自动提示，而不是每个命令都收到提示，则此模式将非常有帮助。
## 配置自动提示
要配置自动提示，您可以按优先顺序使用以下方法：
+ **命令行选项**启用或禁用单个命令的自动提示。使用 `--cli-auto-prompt` 调用自动提示，使用 `--no-cli-auto-prompt` 禁用自动提示。
+ **环境变量**使用 `aws\$1cli\$1auto\$1prompt` 变量。
+ **共享的配置文件**使用 `cli\$1auto\$1prompt` 设置。
# 在 AWS CLI 中控制命令输出
本部分介绍控制 AWS Command Line Interface (AWS CLI) 的输出的不同方式。在终端中自定义 AWS CLI 输出可以提高可读性，简化脚本自动化，并为浏览大型数据集提供便利。
AWS CLI 支持多种[输出格式](cli-usage-output-format.md)，包括 [`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-pagination.md)，而 AWS CLI 则在自己的客户端提供了额外的分页选项。
最后，AWS CLI 具有[服务器端和客户端筛选功能](cli-usage-filter.md)，您可以单独使用一个功能或同时使用这两个功能来筛选 AWS CLI 输出。
**Topics**
+ [敏感输出](#cli-usage-output-sensitive)
+ [服务器端与客户端输出选项](#cli-usage-output-server-client)
+ [在 AWS CLI 中设置输出格式](cli-usage-output-format.md)
+ [AWS CLI 中的结构化错误输出](cli-usage-error-format.md)
+ [在 AWS CLI 中使用分页选项](cli-usage-pagination.md)
+ [在 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 提供支持。客户端筛选使用 `--query` 参数由 AWS CLI 客户端提供支持。
**服务器端**输出选项是 AWS 服务 API 直接支持的功能。任何经过筛选或分页的数据都不会发送到客户端，这可以缩短 HTTP 响应时间，并为较大的数据集提高带宽。
**客户端**输出选项是由 AWS CLI 创建的功能。所有数据都发送到客户端，然后 AWS CLI 会对显示的内容进行筛选或分页。对于较大的数据集，客户端操作不会加快速度或节省带宽。
当服务器端和客户端选项同时使用时，服务器端操作会首先完成，然后发送到客户端进行客户端操作。这利用了服务器端选项可以加快速度和节省带宽的特点，同时使用其他 AWS CLI 功能来获得所需的输出。
# 在 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)主题所述，输出格式可通过三种不同方式指定：
+ **在 `config` 文件的命名配置文件中使用 `output` 选项** – 以下示例将默认输出格式设置为 `text`。
```
[default]
output=text
```
+ **使用 `AWS_DEFAULT_OUTPUT` 环境变量** – 对于此命令行会话中的命令，以下输出将格式设置为 `table`，直到更改此变量或会话结束。使用此环境变量将覆盖在 `config` 文件中设置的任何值。
```
$ export AWS_DEFAULT_OUTPUT="table"
```
+ **在命令行上使用 `--output` 选项** – 以下示例仅将这一个命令的输出设置为 `json`。对此命令使用此选项将覆盖任何当前设置的环境变量或 `config` 文件中的值。
```
$ aws swf list-domains --registration-status REGISTERED --output json
```
**重要**
指定的输出类型更改`--query` 选项的运行方式：
如果您指定 `--output text`，则在应用 `--query` 筛选条件*之前*，输出采用分页方式，并且 AWS CLI 会在输出的*每个页面*上运行查询一次。因此，查询在每个页面上包括第一个匹配元素，这可能会导致意外的额外输出。要进一步筛选输出，您可以使用其他命令行工具，例如 `head` 或 `tail`。
如果您指定 `--output json`、 `--output yaml` 或 `--output yaml-stream`，则在应用 `--query` 筛选条件之前，输出会完全处理为单个本机结构。AWS CLI 仅针对整个结构运行查询一次，同时生成筛选的结果，然后将结果输出。
## JSON 输出格式
[JSON](https://json.org) 是 AWS CLI 的默认输出格式。大多数编程语言可以使用内置函数或公开提供的库轻松解码 JSON 字符串。您可以通过强有力的方式将 JSON 输出与 [--query 选项](cli-usage-filter.md)结合使用，以筛选和格式化 AWS CLI JSON 格式的输出。
对于您可能无法使用 `--query` 执行的更高级的筛选，可以考虑使用 `jq`，这是一个命令行 JSON 处理器。您可以在以下网址下载它并找到正式的教程：[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) 格式的字符串）以编程方式处理输出的情况，如 CloudFormation 及其对 [YAML 格式的模板](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html)的支持，[YAML](https://yaml.org) 是一个很好的选择。
对于您可能无法使用 `--query` 执行的更高级的筛选，可以考虑使用 `yq`，这是一个命令行 YAML 处理器。您可以从 *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` 执行的更高级的筛选，可以考虑使用 `yq`，这是一个命令行 YAML 处理器。您可以从 *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 输出组织为制表符分隔的行。此格式适合在传统 Unix 文本工具（如 `grep`、`sed` 和 `awk`）和由 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
```
第四列是 `PasswordLastUsed` 字段，它对于最后两个条目为空，因为这些用户从未登录过 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` 输出结合使用。第一个命令在 `text` 输出中显示每个实例的可用区、当前状态和实例 ID。第二个命令处理该输出，以仅输出在 `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` 匹配的情况下显示第三列 (`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 的功能（如果跨平台兼容性不是问题）。不像大多数命令 shell 需要的那样将输出处理为文本，PowerShell 让您可以使用 `ConvertFrom-JSON` cmdlet 生成具有层次结构的对象。然后，您可以直接从该对象访问所需的成员。
```
(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId
```
**提示**
如果使用 `--query` 参数输出文本并将输出筛选到单个字段，则输出是单行制表符分隔值。要将每个值放到单独的行上，可以将输出字段放在括号中，如以下示例所示。
制表符分隔的单行输出：
```
$ aws iam list-groups-for-user --user-name susan --output text --query "Groups[].GroupName"
```
```
HRDepartment Developers SpreadsheetUsers LocalAdmins
```
通过将 `[GroupName]` 放在括号中，让每个值都在自己的行上：
```
$ 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` 格式结合使用，以显示从原始输出中预先选择的一系列元素。请注意字典和列表表示法之间的输出区别：在第一个示例中，列名按字母顺序排序；在第二个示例中，未命名的列按用户指定的顺序排序。有关 `--query` 选项的更多信息，请参阅 [在 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 输出格式
`off` 格式禁止向 stdout 输出所有命令输出。这在自动化脚本和 CI/CD 管道中很有用，在这些管道中，您只需检查命令的退出代码而不处理输出。错误消息仍显示在 stderr 上。
下面的示例显示 `off` 格式如何禁止成功的输出。您可以检查退出代码以确定是否成功：
```
$ aws s3api list-buckets --output off
$ echo $?
0
```
如果您使用 Shell 脚本，但希望在不捕获输出的情况下验证资源是否存在，则这一点特别有用：
```
#!/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 服务返回的建模错误成员。
# 在 AWS CLI 中使用分页选项
本主题介绍分页 AWS Command Line Interface（AWS CLI）的输出的不同方式。
主要有两种方法可以从 控制分页AWS CLI
+ [使用服务器端分页参数。](#cli-usage-pagination-serverside)
+ [使用默认输出客户端分页程序](#cli-usage-pagination-clientside)。
服务器端分页参数会先进行处理，然后系统会将所有输出发送到客户端分页程序进行处理。
## 服务器端分页
对于返回大型项目列表的大多数命令，AWS CLI 提供了多个服务器端选项，当 AWS CLI 调用服务 API 以填充此列表时，您可以使用这些选项控制输出中包括的项目数。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 的原定设置页面大小为 1000。如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 `aws s3api list-objects`，则 AWS CLI 将自动对 Amazon S3 发出四次调用，以在后台处理服务特定分页逻辑并在最终输出中返回所有 3500 个对象。
有关特定命令是否具有服务器端分页的信息，请参阅[《AWS CLI 版本 2 参考指南》](https://docs.aws.amazon.com/cli/latest/reference/index.html)。
### 如何使用 --no-paginate 参数
`--no-paginate` 选项在客户端禁用以下分页标记。使用命令时，默认情况下 AWS CLI 会自动执行多次调用，返回所有可能的结果来创建分页。每页显示一次调用的结果。禁用分页时，AWS CLI 只执行一次调用，显示命令结果的第一页。
例如，如果您在包含 3500 个对象的 Amazon S3 存储桶上运行 `aws s3api list-objects`，则 AWS CLI 只会执行对 Amazon S3 的第一个调用，并在最终输出中仅返回前 1000 个对象。
```
$ aws s3api list-objects \
--bucket amzn-s3-demo-bucket \
--no-paginate
{
"Contents": [
...
```
### 如何使用 --page-size 参数
如果您在对大量资源运行列表命令时发现问题，则表明原定设置页面大小可能过大。这可能会导致对 AWS 服务的调用超过允许的最大时间并生成“超时”错误。您可以使用 `--page-size` 选项来指定 AWS CLI 从对 AWS 服务的每个调用请求数量较少的项目。AWS CLI 仍将检索完整列表，但会在后台执行大量服务 API 调用，并减少每次调用时检索的项目数。这样，各个调用成功的可能性会更高且不会发生超时。更改页面大小不会影响输出；它只影响生成输出所需进行的 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` 值，并使您能够检索接下来的 100 个项目。
**注意**
参数 `--starting-token` 不能为空。如果上一个命令未返回 `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` 命令行选项可禁止在单个命令中使用分页程序。
+ 将 `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` 配置文件中的设置。有关配置设置的更多信息，请参阅[AWS CLI 中的配置和凭证文件设置](cli-configure-files.md)。
以下示例将默认输出分页程序设置为 `less` 程序。
```
[default]
cli_pager=less
```
以下示例将默认值设置为禁用分页程序。
```
[default]
cli_pager=
```
### 如何设置 AWS\$1PAGER 环境变量
以下示例将默认输出分页程序设置为 `less` 程序。有关环境变量的更多信息，请参阅[为 AWS CLI 配置环境变量](cli-configure-envvars.md)。
------
#### [ Linux and macOS ]
```
$ export AWS_PAGER="less"
```
------
#### [ Windows ]
```
C:\> setx AWS_PAGER "less"
```
------
### 如何使用 --no-cli-pager 选项
要对单个命令禁止使用分页程序，请使用 `--no-cli-pager` 选项。有关命令行选项的更多信息，请参阅[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` 标志的更多信息，请参阅 *manpages.org* 上的 [less](http://manpages.org/less/1#options)。
------
#### [ Windows ]
如果不另行指定，则 AWS CLI 版本 2 默认使用的分页程序为不带附加标志的 `more`。
以下示例使用 `/c` 参数。
```
C:\> setx AWS_PAGER "more /c"
```
有关 `more` 标志的更多信息，请参阅《Microsoft 文档》**中的 `[more](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/more)`。
------
# 在 AWS CLI 中筛选输出
AWS Command Line Interface（AWS CLI）具有服务器端和客户端筛选功能，您可以单独使用或结合使用这两项功能来筛选 AWS CLI 输出。首先处理服务器端筛选，然后返回输出以进行客户端筛选。
+ 服务器端筛选由 API 提供支持，通常使用 `--filter` 参数来实现筛选。该服务仅返回匹配结果，这可以加快大型数据集的 HTTP 响应时间。
+ 客户端筛选使用 `--query` 参数由 AWS CLI 客户端提供支持。此参数具有服务器端筛选可能没有的功能。
**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` 开头的名称，例如 `--filter-expression` 用于 [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html) 命令。
有关特定命令是否具有服务器端筛选和筛选规则的信息，请参阅 [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 网站*上的[教程](https://jmespath.org/tutorial.html)。
**重要**
指定的输出类型更改`--query` 选项的运行方式：
如果您指定 `--output text`，则在应用 `--query` 筛选条件*之前*，输出采用分页方式，并且 AWS CLI 会在输出的*每个页面*上运行查询一次。因此，查询在每个页面上包括第一个匹配元素，这可能会导致意外的额外输出。要进一步筛选输出，您可以使用其他命令行工具，例如 `head` 或 `tail`。
如果您指定 `--output json`、 `--output yaml` 或 `--output yaml-stream`，则在应用 `--query` 筛选条件之前，输出会完全处理为单个本机结构。AWS CLI 仅针对整个结构运行查询一次，同时生成筛选的结果，然后将结果输出。
**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 式 Shell 编写的。在使用这些示例时，请务必为终端 Shell 使用正确的引用规则。终端解释输入的方式可能会极大地改变发送到 AWS CLI 的内容。终端读取单引号 `'`、双引号 `"` 或反引号 ``` 的方式会更改内容的读取方式。
有关更多信息，请参阅 [在 AWS CLI 中将引号和文本与字符串结合使用](cli-usage-parameters-quoting-strings.md)。
以下 JSON 输出显示了 `--query` 参数可以生成的示例。此输出描述了附加到单独 Amazon EC2 实例的三个 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 网站*上的[标识符](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 网站*上的[索引表达式](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** 是跳过间隔。
**语法**
```
[::]
```
如果 Slice 表达式中忽略了其中任何一个，它们将使用以下默认值：
+ Start – 列表中的第一个索引，0。
+ Stop – 列表中的最后一个索引。
+ Step – 没有跳过步骤，其中值为 1。
要仅返回前两个卷，请使用起始值 0、停止值 2 和步长值 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
}
]
```
由于此示例包含默认值，因此您可以将 Slice 从 `Volumes[0:2:1]` 缩短到 `Volumes[: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
}
]
```
Steps 还可以使用负数按数组的相反顺序进行筛选，如以下示例所示。
```
$ 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 网站*上的[展平](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 网站*上的[筛选表达式](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 网站*上的[传输表达式](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 网站*上的[多选列表](https://jmespath.org/specification.html#multiselectlist)。
### 将标签添加到标识符值
为了使此输出更易于读取，请使用具有以下语法的多选哈希。
**语法**
```
[].{