# 在 Amazon CLI 中设置输出格式 输出格式 本主题介绍了 Amazon Command Line Interface (Amazon CLI) 的不同输出格式。Amazon 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` 筛选条件*之前*，输出采用分页方式，并且 Amazon CLI 会在输出的*每个页面*上运行查询一次。因此，查询在每个页面上包括第一个匹配元素，这可能会导致意外的额外输出。要进一步筛选输出，您可以使用其他命令行工具，例如 `head` 或 `tail`。 如果您指定 `--output json`、 `--output yaml` 或 `--output yaml-stream`，则在应用 `--query` 筛选条件之前，输出会完全处理为单个本机结构。Amazon CLI 仅针对整个结构运行查询一次，同时生成筛选的结果，然后将结果输出。 ## JSON 输出格式 [JSON](https://json.org) 是 Amazon CLI 的默认输出格式。大多数编程语言可以使用内置函数或公开提供的库轻松解码 JSON 字符串。您可以通过强有力的方式将 JSON 输出与 [--query 选项](cli-usage-filter.md)结合使用，以筛选和格式化 Amazon 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) 格式的字符串）以编程方式处理输出的情况，如 Amazon CloudFormation 及其对 [YAML 格式的模板](https://docs.amazonaws.cn/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` 格式将 Amazon 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` 字段，它对于最后两个条目为空，因为这些用户从未登录过 Amazon Web Services 管理控制台。 **重要** *我们强烈建议，如果您指定 `text` 输出，则也始终使用 [`--query`](cli-usage-filter.md) 选项以确保行为一致*。 这是因为文本格式按由 Amazon 服务返回的基础 JSON 对象的键名称以字母顺序对输出列进行排序，而类似的资源可能没有相同的键名称。例如，基于 Linux 的 Amazon EC2 实例的 JSON 表示形式中的元素在基于 Windows 的实例的 JSON 表示形式中可能不存在，反之亦然。此外，资源可能在未来的更新中添加或移除键/值元素，从而修改列的顺序。因此，可以使用 `--query` 补充 `text` 输出的功能，以提供对输出格式的完全控制。 在以下示例中，命令指定要显示的元素，并使用列表表示法 `[key1, key2, ...]` 来*定义列的顺序*。这可让您十分放心：正确的键值始终显示在预期的列中。最后请注意，对于不存在的键，Amazon 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` 格式以表格形式生成复杂 Amazon 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` 选项的更多信息，请参阅 [在 Amazon 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。