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

# 在 中篩選輸出 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/latest/reference/ses/create-receipt-filter.html) 和 [ce](https://docs.aws.amazon.com/cli/latest/reference/ce/get-cost-and-usage.html)。
+ `--filters` 例如 [ec2](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html)、[autoscaling](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-tags.html) 和 [rds](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html)。
+ 以單字 `filter` 開頭來命名，例如對 [https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/scan.html) 命令而言為 `--filter-expression`。

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

## 用戶端篩選
<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`、 `--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)

### 開始之前
<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>

**AWS CLI 自動提示**  
開始使用篩選條件表達式時，您可以使用第 2 AWS CLI 版中的自動提示功能。自動提示功能可在您按下 **F5** 鍵時提供預覽。如需詳細資訊，請參閱 [在 中啟用和使用命令提示字元 AWS CLI](cli-usage-parameters-prompting.md)。

**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/)。