**本文件 AWS CLI 僅適用於 第 1 版。**

我們已宣布即將end-of-support。 AWS CLI 我們建議您遷移至 第 2 AWS CLI 版。如需日期、其他詳細資訊和如何遷移的資訊，請參閱 [公告](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/)。如需 第 2 版的相關文件 AWS CLI，請參閱 第 [2 版使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 中控制命令輸出 AWS CLI
<a name="cli-usage-output"></a>

本節介紹控制 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)、和 [`table`](cli-usage-output-format.md#table-output)。有些服務的資料具有伺服器端[分頁](cli-usage-pagination.md)。

最後， 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-pagination.md)
+ [在 中篩選輸出 AWS CLI](cli-usage-filter.md)

## 敏感輸出
<a name="cli-usage-output-sensitive"></a>

的某些操作 AWS CLI 可能會傳回可能被視為敏感的資訊，包括來自環境變數的資訊。此資訊的暴露在某些情況下可能代表安全風險；例如，資訊可能包含在持續整合和持續部署 (CI/CD) 日誌中。因此，當您將此類輸出作為日誌的一部分時，請務必進行審查，並在不需要時抑制輸出。

如需保護敏感資料的其他資訊，請參閱[中的資料保護 AWS CLI](data-protection.md)。

請考慮下列最佳實務：
+ 考慮以程式設計方式從秘密存放區擷取秘密，例如 AWS Secrets Manager。
+ 檢閱建置日誌的內容，確保其中未包含敏感資訊。考慮輸送到 `/dev/null` 或擷取輸出做為 bash 或 PowerShell 變數等方法來抑制命令輸出。

  以下是將輸出 (而非錯誤) 重新導向至 `/dev/null` 的 bash 範例：

  ```
  $ aws s3 ls > /dev/null
  ```

  如需抑制終端輸出的特定資訊，請參閱您所使用終端的使用者文件。
+ 考慮存取日誌，並根據使用案例適當調整存取範圍。

## 伺服器端與用戶端輸出選項
<a name="cli-usage-output-server-client"></a>

 AWS CLI 具有[伺服器端和用戶端篩選](cli-usage-filter.md)，您可以個別或一起使用來篩選 AWS CLI 輸出。系統會先處理伺服器端篩選，並傳回用戶端篩選的輸出。服務 API 支援伺服器端篩選。用戶端使用 `--query` 參數支援 AWS CLI 用戶端篩選。

**伺服器端**輸出選項是 AWS 服務 API 直接支援的功能。篩選或分頁的任何資料不會傳送至用戶端，這會加速 HTTP 回應時間，並改善較大資料集的頻寬。

**用戶端**輸出選項是由 AWS CLI建立的功能。所有資料都會傳送到用戶端，然後 AWS CLI 篩選或分頁顯示的內容。對於較大的資料集，用戶端操作不會節省速度或頻寬。

當伺服器端和用戶端選項一起使用時，會先完成伺服器端操作，然後傳送至用戶端以進行用戶端操作。這會使用伺服器端選項的潛在速度和省下的頻寬，同時使用其他 AWS CLI 功能來取得所需的輸出。

# 在 中設定輸出格式 AWS CLI
<a name="cli-usage-output-format"></a>

本主題說明 AWS Command Line Interface () 的不同輸出格式AWS CLI。 AWS CLI 支援以下輸出格式：
+ **[`json`](#json-output)** – 輸出的格式為 [JSON](https://json.org/) 字串。
+ **[`text`](#text-output)** – 輸出的格式是多行以 Tab 分隔的字串值。這對於將輸出傳遞給文字處理器 (如 `grep`、`sed` 或 `awk`) 非常有用。
+ **[`table`](#table-output)** – 輸出的格式為使用字元 \$1\$1- 形成儲存格框線的表格。它通常以「方便人類使用」的格式來呈現資訊，這種格式比其他格式更容易閱讀，但在編寫程式方面較不有用。

## 如何選擇輸出格式
<a name="cli-usage-output-format-how"></a>

如同[組態](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`、，系統就會將輸出完全處理為單一原生結構後，才套用 `--query` 篩選條件。只會針對整個結構 AWS CLI 執行一次查詢，產生篩選結果，然後輸出。

## JSON 輸出格式
<a name="json-output"></a>

[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"
        }
    ]
}
```

## 文字輸出格式
<a name="text-output"></a>

`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
```

## 表格輸出格式
<a name="table-output"></a>

`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  |
+--------------+--------------+--------------+-----+
```

# 使用 中的分頁選項 AWS CLI
<a name="cli-usage-pagination"></a>

本主題說明從 AWS Command Line Interface () 分頁輸出的不同方式AWS CLI。

## 伺服器端分頁
<a name="cli-usage-pagination-serverside"></a>

對於傳回大量項目清單的大多數命令， AWS CLI 具有多個伺服器端選項，可在 AWS CLI 呼叫服務的 API 填入清單時控制輸出中包含的項目數量。中的伺服器端分頁由 AWS 服務 API AWS CLI 啟用，因此這些選項只有在服務 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。例如，如果您在包含 3,500 個物件的 Amazon S3 儲存貯體上執行 `aws s3api list-objects`， AWS CLI 會自動對 Amazon S3 進行 4 次呼叫、在背景為您處理服務特定的分頁邏輯，並在最終輸出中傳回全部 3,500 個物件。

如需特定命令是否具有伺服器端分頁的資訊，請參閱[AWS CLI 參考指南](https://docs.aws.amazon.com/cli/v1/reference/)第 。

### 如何使用 --no-paginate 參數
<a name="cli-usage-pagination-nopaginate"></a>

`--no-paginate` 選項在客户端停用以下分頁標記。使用命令時，根據預設， AWS CLI 會自動進行多次呼叫，以傳回所有可能的結果來建立分頁。每個頁面一個呼叫。停用分頁對於命令結果的第一頁 AWS CLI 只有一次呼叫。

例如，如果您在包含 3，500 個物件的 Amazon S3 儲存貯體`aws s3api list-objects`上執行 ，則 AWS CLI 只會對 Amazon S3 進行第一次呼叫，並在最終輸出中僅傳回前 1，000 個物件。

```
$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --no-paginate
{
    "Contents": [
...
```

### 如何使用 --page-size 參數
<a name="cli-usage-pagination-pagesize"></a>

如果您在針對大量資源執行清單命令時發生問題，可能是預設頁面大小太高。這可能會導致對 AWS 服務的呼叫超過允許的時間上限，並產生「逾時」錯誤。您可以使用 `--page-size`選項來指定從每次呼叫對 AWS 服務 AWS CLI 請求較少數量的項目。 AWS CLI 仍會擷取完整清單，但在背景執行更多數量的服務 API 呼叫，並在每次呼叫時擷取較少數量的項目。這可讓每次呼叫不逾時的成功機會更高。變更頁面大小不會影響輸出；它只會影響產生輸出所需進行的 API 呼叫數量。

```
$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --page-size 100
{
    "Contents": [
...
```

### 如何使用 --max-items 參數
<a name="cli-usage-pagination-maxitems"></a>

若要一次在 AWS CLI 輸出中包含較少的項目，請使用 `--max-items`選項。 AWS CLI 仍會如先前所述使用 服務處理分頁，但一次只會列印您指定的項目數量。

```
$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --max-items 100
{
    "NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==",
    "Contents": [
...
```

### 如何使用 --starting-token 參數
<a name="cli-usage-pagination-startingtoken"></a>

如果項目輸出數量 (`--max-items`) 少於基礎 API 呼叫傳回的項目總數，則輸出會包含一個 `NextToken`，提供您在後續命令中傳送以擷取下一組項目。以下範例說明如何使用前一範例傳回的 `NextToken` 值，並讓您擷取第二批的 100 個項目。

**注意**  
參數 `--starting-token` 不能為 null 或空白。如果先前的命令未傳回 `NextToken` 值，表示已沒有更多項目可傳回，您也不需要再次呼叫命令。

```
$ aws s3api list-objects \
    --bucket amzn-s3-demo-bucket \
    --max-items 100 \
    --starting-token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxfQ==
{
    "Contents": [
...
```

每次呼叫 時，指定的 AWS 服務可能不會以相同的順序傳回項目。如果您為 `--page-size` 和 `--max-items` 指定不同的數值，您可能會取得意外的結果，並發生遺漏或重複的項目。欲避免此情況，請對 `--page-size` 和 `--max-items` 使用相同數字，以同步 AWS CLI 和基礎服務的分頁。您亦可擷取整個清單，並於本機執行所需的分頁操作。

# 在 中篩選輸出 AWS CLI
<a name="cli-usage-filter"></a>

 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)

## 伺服器端篩選
<a name="cli-usage-filter-server-side"></a>

中的伺服器端篩選由 AWS 服務 API AWS CLI 提供。 AWS 服務僅會傳回符合您篩選條件 HTTP 回應中的記錄，其可加速大型資料集的 HTTP 回應時間。由於伺服器端篩選是由服務 API 定義，參數名稱和函數會因服務而異。部分用於篩選的常見參數名稱有：
+ `--filter` 例如 [ses](https://docs.aws.amazon.com/cli/v1/reference/ses/create-receipt-filter.html) 和 [ce](https://docs.aws.amazon.com/cli/v1/reference/ce/get-cost-and-usage.html)。
+ `--filters` 例如 [ec2](https://docs.aws.amazon.com/cli/v1/reference/ec2/describe-volumes.html)、[autoscaling](https://docs.aws.amazon.com/cli/v1/reference/autoscaling/describe-tags.html) 和 [rds](https://docs.aws.amazon.com/cli/v1/reference/rds/describe-db-instances.html)。
+ 以單字 `filter` 開頭來命名，例如對 [https://docs.aws.amazon.com/cli/v1/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/v1/reference/dynamodb/scan.html) 命令而言為 `--filter-expression`。

如需特定命令是否具有伺服器端篩選和篩選規則的資訊，請參閱[AWS CLI 參考指南](https://docs.aws.amazon.com/cli/v1/reference/)第 。

## 用戶端篩選
<a name="cli-usage-filter-client-side"></a>

使用 `--query` 參數 AWS CLI 提供內建的 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`、，系統就會將輸出完全處理為單一原生結構後，才套用 `--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)

### 開始之前
<a name="cli-usage-filter-client-side-output"></a>

**注意**  
這些篩選條件表達式範例是針對基本類似 Linux 的 shell 撰寫的。使用這些範例時，請務必為終端 Shell 使用正確引號規則。終端解譯輸入的方式可能會大幅變更傳送至 AWS CLI的內容。終端讀取單引號 `'`、雙引號 `"` 或反引號 ``` 的方式會改變讀取內容的方式。  
如需詳細資訊，請參閱[在 中使用引號和常值搭配字串 AWS CLI](cli-usage-parameters-quoting-strings.md)。

以下 JSON 輸出會顯示如何產生 `--query` 參數之範例。輸出會描述連接到不同 Amazon EC2 執行個體的三個 Amazon EBS 磁碟區。

#### 範例輸出
<a name="cli-usage-filter-client-side-output-example"></a>

```
$ 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
    }
  ]
}
```

### 識別碼
<a name="cli-usage-filter-client-side-identifiers"></a>

識別碼是輸出值的標籤。在建立篩選條件時，您可以使用識別碼來縮小查詢結果範圍。在下列輸出範例中，所有識別碼 (例如 `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 )。

### 從清單中選取
<a name="cli-usage-filter-client-side-select-list"></a>

輕單或陣列為後接方括號 `[` 的識別碼，例如 [開始之前](#cli-usage-filter-client-side-output) 中的 `Volumes` 和 `Attachments`。

**語法**

```
<listName>[ ]
```

若要從陣列中篩選所有輸出，您可以使用萬用表示法。[萬用字元](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** 則是略過間隔。

**語法**

```
<arrayName>[<start>:<stop>:<step>]
```

如果從配量表達式中省略了其中任何一個，則會使用下列預設值：
+ Start – 清單中的第一個索引，值為 0。
+ Stop – 清單中的最後一個索引。
+ Step – 未略過步驟，其數值為 1。

若只要傳回前兩個磁碟區，您可以使用 start 數值 0、stop 數值 2，以及 step 數值 1，如下列範例所示。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[0:2:1]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-18T20:26:16.000Z",
        "InstanceId": "i-4b41a37c",
        "VolumeId": "vol-2e410a47",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-2e410a47",
    "State": "in-use",
    "SnapshotId": "snap-708e8348",
    "CreateTime": "2013-09-18T20:26:15.000Z",
    "Size": 8
  }
]
```

由於此範例中包含預設值，您可以將配量從 `Volumes[0:2:1]` 縮短至 `Volumes[:2]`。

下列範例會省略預設值，並傳回整個陣列中的每兩個磁碟區。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[::2]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2020-11-20T19:54:06.000Z",
        "InstanceId": "i-1jd73kv8",
        "VolumeId": "vol-a1b3c7nd",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-a1b3c7nd",
    "State": "in-use",
    "SnapshotId": "snap-234087fb",
    "CreateTime": "2020-11-20T19:54:05.000Z",
    "Size": 15
  }
]
```

Step 也可以使用負數並以與陣列相反的順序來篩選，如下列範例所示。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[::-2]'
[
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2020-11-20T19:54:06.000Z",
        "InstanceId": "i-1jd73kv8",
        "VolumeId": "vol-a1b3c7nd",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-a1b3c7nd",
    "State": "in-use",
    "SnapshotId": "snap-234087fb",
    "CreateTime": "2020-11-20T19:54:05.000Z",
    "Size": 15
  },
  {
    "AvailabilityZone": "us-west-2a",
    "Attachments": [
      {
        "AttachTime": "2013-09-17T00:55:03.000Z",
        "InstanceId": "i-a071c394",
        "VolumeId": "vol-e11a5288",
        "State": "attached",
        "DeleteOnTermination": true,
        "Device": "/dev/sda1"
      }
    ],
    "VolumeType": "standard",
    "VolumeId": "vol-e11a5288",
    "State": "in-use",
    "SnapshotId": "snap-f23ec1c8",
    "CreateTime": "2013-09-17T00:55:03.000Z",
    "Size": 30
  }
]
```

如需詳細資訊，請參閱 *JMESPath 網站*上的[配量](https://jmespath.org/specification.html#slices)。

### 篩選巢狀資料
<a name="cli-usage-filter-client-side-nested"></a>

若要縮小對巢狀值 `Volumes[*]` 的篩選範圍，您可以附加句點以及您的篩選條件標準來使用子運算式。

**語法**

```
<expression>.<expression>
```

以下範例顯示所有磁碟區的所以 `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"
    }
  ]
]
```

若要進一步篩選巢狀值，請附加每個巢狀識別碼的表達式。以下範例會列出所有 `Volumes` 的 `State`。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Attachments[*].State'
[
  [
    "attached"
  ],
  [
    "attached"
  ],
  [
    "attached"
  ]
]
```

### 扁平化結果
<a name="cli-usage-filter-client-side-specific-flattening"></a>

如需詳細資訊，請參閱 *JMESPath 網站*上的[子運算式](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)。

### 篩選特定值
<a name="cli-usage-filter-client-side-specific-values"></a>

若要篩選清單中的特定值，您可以使用篩選條件表達式，如下列語法所示。

**語法**

```
? <expression> <comparator> <expression>]
```

表達式比較子包括 `==`、`!=`、`<`、`<=`、`>` 和 `>=`。下列範例會篩選 `Attached``State` 中所有 `Volumes` 的 `VolumeIds`。

```
$ 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"
]
```

下列範例會篩選所有 `Volumes` 中規模小於 20 的 `VolumeIds`。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?Size < `20`].VolumeId'
[
  "vol-2e410a47",
  "vol-a1b3c7nd"
]
```

如需詳細資訊，請參閱 *JMESPath 網站*上的[篩選條件表達式](https://jmespath.org/specification.html#filterexpressions)。

### 輸送表達式
<a name="cli-usage-filter-client-side-pipe"></a>

您可以將篩選結果輸送至新清單，然後透過下列語法利用另一個表達式來篩選結果：

**語法**

```
<expression> | <expression>] 
```

下列範例會採用 `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)。

### 篩選多個識別碼值
<a name="cli-usage-filter-client-side-miltiselect-list"></a>

若要篩選多個識別碼，您可以透過下列語法來使用複選清單：

**語法**

```
<listName>[].[<expression>, <expression>]
```

在以下範例中，`VolumeId` 和 `VolumeType` 會在 `Volumes` 清單受到篩選，以產生下列表達式。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].[VolumeId, VolumeType]'
[
  [
    "vol-e11a5288",
    "standard"
  ],
  [
    "vol-2e410a47",
    "standard"
  ],
  [
    "vol-a1b3c7nd",
    "standard"
  ]
]
```

若要將巢狀資料新增至清單，請新增另一個複選清單。以下範例會透過在巢狀 `Attachments` 清單中篩選 `InstanceId` 和 `State` 來擴展上述範例。成果如以下表達式。

```
$ 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)。

### 將標籤新增至識別碼值
<a name="cli-usage-filter-client-side-multiselect-hash"></a>

為了使此輸出更容易閱讀，請使用具有以下語法的複選雜湊。

**語法**

```
<listName>[].{<label>: <expression>, <label>: <expression>}
```

您的識別碼標籤不需與識別碼的名稱相同。以下範例會將 `VolumeType` 標籤用於 `VolumeType` 值。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeType: VolumeType}'
[
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  },
  {
    "VolumeType": "standard",
  }
]
```

為了簡單起見，下列範例會保留每個標籤的識別碼名稱，並顯示所有磁碟區的 `VolumeId`、`VolumeType`、`InstanceId` 以及 `State`：

```
$ aws ec2 describe-volumes \
    --query 'Volumes[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  },
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  }
]
```

如需詳細資訊，請參閱 *JMESPath 網站*上的[複選雜湊](https://jmespath.org/specification.html#multiselecthash)。

### 函數
<a name="cli-usage-filter-client-side-functions"></a>

JMESPath 語法包含許多可用於查詢的功能。如需 JMESPath 函數的相關資訊，請參閱 *JMESPath 網站*上的[內建函數](https://jmespath.org/specification.html#built-in-functions)。

為了示範如何將函數合併至您的查詢中，下列範例會使用 `sort_by` 函數。`sort_by` 函數會使用以下語法，利用表達式作為排序索引鍵來排序陣列：

**語法**

```
sort_by(<listName>, <sort expression>)[].<expression>
```

下列範例會使用先前的[複選雜湊範例](#cli-usage-filter-client-side-multiselect-hash)，並藉由 `VolumeId` 來排序輸出。

```
$ aws ec2 describe-volumes \
    --query 'sort_by(Volumes, &VolumeId)[].{VolumeId: VolumeId, VolumeType: VolumeType, InstanceId: Attachments[0].InstanceId, State: Attachments[0].State}'
[
  {
    "VolumeId": "vol-2e410a47",
    "VolumeType": "standard",
    "InstanceId": "i-4b41a37c",
    "State": "attached"
  },
  {
    "VolumeId": "vol-a1b3c7nd",
    "VolumeType": "standard",
    "InstanceId": "i-1jd73kv8",
    "State": "attached"
  },
  {
    "VolumeId": "vol-e11a5288",
    "VolumeType": "standard",
    "InstanceId": "i-a071c394",
    "State": "attached"
  }
]
```

如需詳細資訊，請參閱 *JMESPath 網站*上的 [sort\$1by](https://jmespath.org/specification.html#sort-by)。

### 進階 `--query` 範例
<a name="cli-usage-filter-client-side-advanced"></a>

**從特定項目中擷取資訊**

以下範例使用 `--query` 參數來尋找清單中的特定項目，然後從該項目中擷取資訊。該範例會列出與指定服務端點相關的所有 `AvailabilityZones`。它從具有指定 `ServiceName` 的 `ServiceDetails` 清單擷取項目，然後從該選取項目輸出 `AvailabilityZones` 欄位。

```
$ aws --region us-east-1 ec2 describe-vpc-endpoint-services \
    --query 'ServiceDetails[?ServiceName==`com.amazonaws.us-east-1.ecs`].AvailabilityZones'
[
    [
        "us-east-1a",
        "us-east-1b",
        "us-east-1c",
        "us-east-1d",
        "us-east-1e",
        "us-east-1f"
    ]
]
```

**顯示指定建立日期之後的快照**

以下範例說明如何列出在指定日期之後建立的所有快照，並只包括輸出中的幾個可用欄位。

```
$ aws ec2 describe-snapshots --owner self \
    --output json \
    --query 'Snapshots[?StartTime>=`2018-02-07`].{Id:SnapshotId,VId:VolumeId,Size:VolumeSize}'
[
    {
        "id": "snap-0effb42b7a1b2c3d4",
        "vid": "vol-0be9bb0bf12345678",
        "Size": 8
    }
]
```

**顯示最近的 AMI**

以下範例會列出您建立的 5 個最新 Amazon Machine Image (AMI)，依最新到最舊排列。

```
$ aws ec2 describe-images \
    --owners self \
    --query 'reverse(sort_by(Images,&CreationDate))[:5].{id:ImageId,date:CreationDate}'
[
    {
        "id": "ami-0a1b2c3d4e5f60001",
        "date": "2018-11-28T17:16:38.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60002",
        "date": "2018-09-15T13:51:22.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60003",
        "date": "2018-08-19T10:22:45.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60004",
        "date": "2018-05-03T12:04:02.000Z"
    },
    {
        "id": "ami-0a1b2c3d4e5f60005",
        "date": "2017-12-13T17:16:38.000Z"
    }
]
```

**顯示狀況不良的 Auto Scaling 執行個體**

以下範例僅會顯示指定 Auto Scaling 群組中任何狀況不良的執行個體的 `InstanceId`。

```
$ aws autoscaling describe-auto-scaling-groups \
    --auto-scaling-group-name My-AutoScaling-Group-Name \
    --output text \
    --query 'AutoScalingGroups[*].Instances[?HealthStatus==`Unhealthy`].InstanceId'
```

**包含有指定標籤的磁碟區**

以下範例描述所有具備 `test` 標籤的執行個體。只要 `test` 旁邊有另一個附加至磁碟區的標籤，則磁碟區仍會傳回結果中。

下列表達式傳回陣列中具有 `test` 標籤的所有標籤。任何不是 `test` 標籤的標籤都包含 `null` 值。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

**排除有指定標籤的磁碟區**

以下範例描述所有沒有 `test` 標籤的執行個體。使用簡易 `?Value != `test`` 表達式之方式，不適用於排除磁碟區，原因是磁碟區可擁有多個標籤。只要 `test` 旁邊有另一個附加至磁碟區的標籤，則磁碟區仍會傳回結果中。

若要排除所有具有 `test` 標籤的磁碟區，請從以下表達式開始傳回陣列中所有具有 `test` 標籤的標籤。任何不是 `test` 標籤的標籤都包含 `null` 值。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[*].Tags[?Value == `test`]'
```

接著，請使用 `not_null` 函數篩選掉所有正向 `test` 結果。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)]'
```

輸送結果，以展平會導致以下查詢的結果。

```
$ aws ec2 describe-volumes \
    --query 'Volumes[?!not_null(Tags[?Value == `test`].Value)] | []'
```

## 結合伺服器端和用戶端篩選
<a name="cli-usage-filter-combining"></a>

您可以將伺服器端和用戶端篩選搭配著使用。先完成伺服器端篩選，再將資料傳送至 `--query` 參數稍後要篩選的用戶端。如果您使用的是大型資料集，則首先使用伺服器端篩選可以降低每次 AWS CLI 呼叫傳送至用戶端的資料量，同時保持用戶端篩選提供的強大自訂功能。

以下範例會列出同時使用伺服器端和用戶端篩選的 Amazon EC2 磁碟區。此服務會篩選 `us-west-2a` 可用區域內所有附加磁碟區。`--query` 參數會將輸出進一步限制為 `Size` 數值大於 50 的那些磁碟區，並只顯示具有使用者定義名稱的指定欄位。

```
$ aws ec2 describe-volumes \
    --filters "Name=availability-zone,Values=us-west-2a" "Name=status,Values=attached" \
    --query 'Volumes[?Size > `50`].{Id:VolumeId,Size:Size,Type:VolumeType}'
[
    {
        "Id": "vol-0be9bb0bf12345678",
        "Size": 80,
        "VolumeType": "gp2"
    }
]
```

以下範例擷取符合幾個條件的影像清單。接著使用 `--query` 參數來依照 `CreationDate` 排序輸出，只選擇最新的項目。最後，顯示該映像的 `ImageId`。

```
$ aws ec2 describe-images \
    --owners amazon \
    --filters "Name=name,Values=amzn*gp2" "Name=virtualization-type,Values=hvm" "Name=root-device-type,Values=ebs" \
    --query "sort_by(Images, &CreationDate)[-1].ImageId" \
    --output text
ami-00ced3122871a4921
```

以下範例透過使用 `length` 計算清單中有多少項目數，顯示超過 1000 IOPS 的可用磁碟區數。

```
$ aws ec2 describe-volumes \
    --filters "Name=status,Values=available" \
    --query 'length(Volumes[?Iops > `1000`])'
3
```

下列範例會擷取在使用 CloudFormation 堆疊的指定 中，使用啟動組態 AWS 區域 的 Auto Scaling 群組名稱。

```
$ aws autoscaling describe-auto-scaling-groups --region us-west-2 \
  --filters Name=tag-key,Values=aws:cloudformation:stack-name \
  --query 'AutoScalingGroups[?LaunchConfigurationName!=`null`].AutoScalingGroupName'
[
    "group-1",
    "group-2",
    "group-3"
]
```

## 其他資源
<a name="cli-usage-filter-resources"></a>

**JMESPath 終端機**  
JMESPath 終端機為交互式終端命令，與用於用戶端篩選的 JMESPath 表達式一起進行實驗。使用 `jpterm` 命令時，終端機會在您輸入時立即顯示查詢結果。您可以直接將 AWS CLI 輸出輸送至終端機，啟用進階查詢實驗。  
下列範例會直接輸送 `aws ec2 describe-volumes` 輸出至 JMESPath 終端機。  

```
$ aws ec2 describe-volumes | jpterm
```
如需 JMESPath 終端機和安裝說明的詳細資訊，請參閱 *GitHub* 上的 [JMESPath 終端機](https://github.com/jmespath/jmespath.terminal)。

**jq 公用程式**  
`jq` 公用程式會提供一個方法，讓您能將用戶端的輸出轉換為您要的輸出格式。如需 `jq` 和安裝說明的詳細資訊，請參閱 *GitHub* 上的 [jq](https://stedolan.github.io/jq/)。