本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 中控制命令輸出 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)、[`off`](cli-usage-output-format.md#off-output)、 [`yaml`](cli-usage-output-format.md#yaml-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)** – 輸出的格式是多行以 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。 # 中的結構化錯誤輸出 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". ``` **範例：不存在的 Lambda 函數與其他欄位** ``` aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 Additional error details: Type: User ``` 「其他錯誤詳細資訊」區段只會顯示服務錯誤形狀模型中定義的欄位。不會顯示來自錯誤回應的未建模欄位。 **範例：複雜錯誤欄位** ``` 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 format (JSON 格式) JSON 格式提供包含所有錯誤欄位的結構化表示。 **範例：缺少區域組態** ``` { "Code": "NoRegion", "Message": "You must specify a region. You can also configure your region by running \"aws configure\"." } ``` **範例：不存在的 Lambda 函數** ``` { "Code": "ResourceNotFoundException", "Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345", "Type": "User" } ``` ### YAML 格式 YAML 格式提供包含所有錯誤欄位的結構化表示。 **範例：缺少區域組態** ``` Code: NoRegion Message: You must specify a region. You can also configure your region by running "aws configure". ``` **範例：不存在的 Lambda 函數** ``` Code: ResourceNotFoundException Message: "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345" Type: User ``` ### 文字格式 文字格式使用與成功命令輸出相同的格式器。 **範例：不存在的 Lambda 函數** ``` ResourceNotFoundException Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 User ``` ### 資料表格式 資料表格式使用與成功命令輸出相同的格式器。 **範例：不存在的 Lambda 函數** ``` ------------------------------------------------------------------------------------------------------------------------------------| | error | +----------------------------+--------------------------------------------------------------------------------------------------+------+ | Code | Message | Type | +----------------------------+--------------------------------------------------------------------------------------------------+------+ | ResourceNotFoundException | Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 | User | +----------------------------+--------------------------------------------------------------------------------------------------+------+ ``` ### 舊版格式 舊版格式提供不含結構化詳細資訊的原始錯誤格式。此格式不包含 CLI 例外狀況的「發生錯誤 (ErrorCode)：」字首。 **範例：缺少區域組態** ``` aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure". ``` **範例：不存在的 Lambda 函數** ``` An error occurred (ResourceNotFoundException) when calling the GetFunction operation: Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345 ``` **注意** 錯誤現在會持續包含 CLI 例外狀況的`aws: [ERROR]:`字首。舊版不一定包含此字首。 無論設定的錯誤格式為何，下列例外一律使用舊版格式： `UnknownArgumentError` – 顯示用量資訊 鍵盤中斷 (`KeyboardInterrupt`) ## 完成範例 下列範例顯示具有 JSON 錯誤格式的命令： ``` $ aws lambda get-function \ --function-name nonexistent-function-12345 \ --cli-error-format json ``` 輸出 (stderr)： ``` { "Code": "ResourceNotFoundException", "Message": "Function not found: arn:aws:lambda:us-west-2:123456789012:function:nonexistent-function-12345", "Type": "User" } ``` `Type` 欄位是 Lambda 服務錯誤形狀中定義的模型化錯誤成員。只有服務錯誤模型中定義的欄位才會包含在結構化錯誤輸出中。 # 使用 中的分頁選項 AWS CLI 本主題說明從 AWS Command Line Interface () 分頁輸出的不同方式AWS CLI。 主要有兩種方法來控制 AWS CLI輸出的分頁。 + [使用伺服器端的分頁參數。](#cli-usage-pagination-serverside) + [使用您的預設輸出用戶端分頁程式](#cli-usage-pagination-clientside)。 伺服器端分頁參數先處理，然後所有輸出都傳送到用戶端分頁。 ## 伺服器端分頁 對於傳回大量項目清單的大多數命令， 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 2 版參考指南](https://docs.aws.amazon.com/cli/latest/reference/index.html)。 ### 如何使用 --no-paginate 參數 `--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 參數 如果您在針對大量資源執行清單命令時發生問題，可能是預設頁面大小太高。這可能會導致對 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` 不能為 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 第 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 ] 如果您未另外指定，分頁器第 2 AWS CLI 版預設使用 `less`。如果您沒有設定`LESS`環境變數，第 2 AWS CLI 版會使用 `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 Docs* 的 `[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 服務 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)。 ## 用戶端篩選 使用 `--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) ### 開始之前 **注意** 這些篩選條件表達式範例是針對基本類似 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 )。 ### 從清單中選取 輕單或陣列為後接方括號 `[` 的識別碼，例如 [開始之前](#cli-usage-filter-client-side-output) 中的 `Volumes` 和 `Attachments`。 **語法** ``` [ ] ``` 若要從陣列中篩選所有輸出，您可以使用萬用表示法。[萬用字元](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** 則是略過間隔。 **語法** ``` [::] ``` 如果從配量表達式中省略了其中任何一個，則會使用下列預設值： + 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)。 ### 篩選巢狀資料 若要縮小對巢狀值 `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" } ] ] ``` 若要進一步篩選巢狀值，請附加每個巢狀識別碼的表達式。以下範例會列出所有 `Volumes` 的 `State`。 ``` $ aws ec2 describe-volumes \ --query 'Volumes[*].Attachments[*].State' [ [ "attached" ], [ "attached" ], [ "attached" ] ] ``` ### 扁平化結果 如需詳細資訊，請參閱 *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)。 ### 篩選特定值 若要篩選清單中的特定值，您可以使用篩選條件表達式，如下列語法所示。 **語法** ``` ? ] ``` 表達式比較子包括 `==`、`!=`、`<`、`<=`、`>` 和 `>=`。下列範例會篩選 `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)。 ### 輸送表達式 您可以將篩選結果輸送至新清單，然後透過下列語法利用另一個表達式來篩選結果： **語法** ``` | ] ``` 下列範例會採用 `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" ] ] ``` 若要將巢狀資料新增至清單，請新增另一個複選清單。以下範例會透過在巢狀 `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)。 ### 將標籤新增至識別碼值 為了使此輸出更容易閱讀，請使用具有以下語法的複選雜湊。 **語法** ``` [].{