本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 中設定輸出格式 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)** – 輸出的格式是多行以 Tab 分隔的字串值。這對於將輸出傳遞給文字處理器 (如 `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) 是使用發出或消耗 [YAML](https://yaml.org) 格式字串的服務和工具以程式設計方式處理輸出的好選擇，例如 CloudFormation 支援 [YAML 格式的範本](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html)。
您可能無法使用 `--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` 搭配來自 `aws ec2 describe-instances` 命令的 `text` 輸出。第一個命令顯示可用區域、目前狀態，以及 `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` 輸出中的欄以 Tab 鍵分隔，因此您可以使用 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 的能力，當您無須擔心跨平台相容性時，即可使用。PowerShell 可讓您使用 `ConvertFrom-JSON` cmdlet 產生階層結構化物件，而非以文字形式處理輸出。然後，您可以直接從該物件存取您想要的成員。
```
(aws ec2 describe-instances --output json | ConvertFrom-Json).Reservations.Instances.InstanceId
```
**提示**
如果您輸出文字並使用 `--query` 參數將輸出篩選為單一欄位，則輸出會是單行標籤分隔值。若要將每個數值放在單獨的行上，您可以用括弧括住輸出欄位，如下列範例所示。
Tab 分隔的單行輸出：
```
$ 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` 格式會隱藏 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。