**本文件 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 中指定參數值
AWS Command Line Interface (AWS CLI) 所用的許多參數都是簡單的字串或數字值，例如以下 `aws ec2 create-key-pair` 命令範例中的金鑰對名稱 `my-key-pair`。
```
$ aws ec2 create-key-pair --key-name my-key-pair
```
終端之間的命令格式可能有所不同。例如，大多數終端機是區分大小寫的，但 Powershell 不區分大小寫。這代表以下兩個命令範例會為區分大小寫的終端產生不同的結果，因為它們將 `MyFile*.txt` 和 `myfile*.txt` 視為**不同**的參數。
但是，PowerShell 會處理這些請求，因為它會將 `MyFile*.txt` 和 `myfile*.txt`視作**相同**的參數。下列命令範例使用 `aws s3 cp` 命令示範這些參數：
```
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "MyFile*.txt"
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "myfile*.txt"
```
有關 PowerShell 不區分大小寫的詳細資訊，請參閱 *PowerShell 文件*中的[關於不區分大小寫](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_case-sensitivity)。
有時您需要在包含特殊或空格字元的字串周圍使用引號或文字。有關此格式的規則也可能在終端機之間有所不同。如需有關在複雜參數周圍使用引號的詳細資訊，請參閱 [在 中使用引號和常值搭配字串 AWS CLI](cli-usage-parameters-quoting-strings.md)。
這些主題涵蓋最常見的終端格式化規則。如果您的終端辨識參數值發生問題，請務必檢閱本節中的主題，並檢查終端的文件是否有其特定的語法規則。
**Topics**
+ [中的常見參數類型 AWS CLI](cli-usage-parameters-types.md)
+ [在 中使用引號和常值搭配字串 AWS CLI](cli-usage-parameters-quoting-strings.md)
+ [從 中的檔案載入參數 AWS CLI](cli-usage-parameters-file.md)
+ [AWS CLI 中的骨架和輸入檔案 AWS CLI](cli-usage-skeleton.md)
+ [在 中使用速記語法 AWS CLI](cli-usage-shorthand.md)
# 中的常見參數類型 AWS CLI
本節說明一些常見的參數類型和典型必要格式。
如果您對特定命令的參數格式有問題，請在命令名稱後輸入 **help** 來檢視說明。每個子命令的幫助包括選項的名稱和說明。該選項的參數類型在括弧中列出。如需檢視說明的詳細資訊，請參閱 [存取 的說明和資源 AWS CLI](cli-usage-help.md)。
**Topics**
+ [String](#parameter-type-string)
+ [時間戳記](#parameter-type-timestamp)
+ [清單](#parameter-type-list)
+ [Boolean](#parameter-type-boolean)
+ [Integer](#parameter-type-integer)
+ [Binary/Blob (二進位大型物件)和串流 Blob](#parameter-type-blobs)
+ [Map](#parameter-type-map)
+ [文件](#parameter-type-document)
## String
字串參數可以包含 [ASCII](https://wikipedia.org/wiki/ASCII) 字元集的英數字元、符號和空格。包含空格的字串必須用引號括起來。我們建議您不要使用標準空格字元以外的符號和空格，並觀察終端機的[引用規則](cli-usage-parameters-quoting-strings.md)以防止意外結果。
某些字串參數可以接受檔案中的二進位資料。如需範例，請參閱[二進位檔案](cli-usage-parameters-file.md#cli-usage-parameters-file-binary)。
## 時間戳記
根據 [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 標準對時間戳記進行格式化。這些通常稱為「`DateTime`」或「`Date`」參數。
```
$ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z
```
可接受的格式包括：
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (UTC)*，例如 2014-10-01T20:30:00.000Z
+ *YYYY*-*MM*-*DD*T*hh*:*mm*:*ss.sss**TZD (包含偏移)*，例如 2014-10-01T12:30:00.000-08:00
+ *YYYY*-*MM*-*DD*，例如 2014-10-01
+ Unix 時間 (以秒為單位)，例如 1412195400。這有時稱為 [Unix Epoch 時間](https://wikipedia.org/wiki/Unix_time)，表示為 1970 年 1 月 1 日午夜 (UTC 時間) 以來的秒數。
您可以透過使用 `cli\$1timestamp\$1format` 檔案設定來設定時間戳記格式。
## 清單
由空格分隔的一個或多個字串。如果任何字串項目包含空格，就必須使用引號括住該項目。遵守您的終端機的[引號規則](cli-usage-parameters-quoting-strings.md)以防止意外結果。
```
$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium
```
## Boolean
可開啟或關閉選項的二進位標記。例如，`ec2 describe-spot-price-history` 有一個布林值 `--dry-run` 參數，當指定時，可以在不實際執行查詢的情況下針對服務驗證查詢。
```
$ aws ec2 describe-spot-price-history --dry-run
```
輸出表明該命令的格式是否正確。此命令還包含一個 `--no-dry-run` 版本的參數，可用於明確指示該命令應該正常執行。包括它並不是必須的，因為這是預設行為。
## Integer
一個不帶正負號的整數。
```
$ aws ec2 describe-spot-price-history --max-items 5
```
## Binary/Blob (二進位大型物件)和串流 Blob
在 中 AWS CLI，您可以直接在命令列上以字串形式傳遞二進位值。Blob 有兩種：
+ [Blob](#parameter-type-blob)
+ [串流 Blob](#parameter-type-streaming-blob)
### Blob
若要將值傳遞至類型為 `blob` 的參數，您必須使用 `fileb://` 字首為包含二進位資料的本機檔案指定路徑。使用 `fileb://` 字首參考的檔案一律視為原始未編碼的二進位。指定的路徑會解譯為相對於目前的工作目錄。例如，`aws kms encrypt` 的 `--plaintext` 參數是一個 blob。
```
$ aws kms encrypt \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--plaintext fileb://ExamplePlaintextFile \
--output text \
--query CiphertextBlob | base64 \
--decode > ExampleEncryptedFile
```
### 串流 Blob
`aws cloudsearchdomain upload-documents` 等串流 blob 不使用字首。而是使用直接檔案路徑來格式化串流 Blob 參數。下列範例將直接檔案路徑 `document-batch.json` 用於 `aws cloudsearchdomain upload-documents` 命令：
```
$ aws cloudsearchdomain upload-documents \
--endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \
--content-type application/json \
--documents document-batch.json
```
## Map
以 JSON 或使用 CLI [速記語法](cli-usage-shorthand.md)指定的鍵/值對組。以下 JSON 範例從名為 *my-table* 的 Amazon DynamoDB 表格中讀取一個項目，並附帶地圖參數 `--key`。該參數指定一個名為 *id* 的主金鑰，其在巢狀的 JSON 結構中具有數值 *1*。
若要在命令列中使用更進階的 JSON，請考慮使用 `jq` 之類的命令列 JSON 處理器來建立 JSON 字串。如需 `jq` 的詳細資訊，請參閱 *GitHub* 上的 [jq 儲存庫](http://stedolan.github.io/jq/)。
```
$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}'
{
"Item": {
"name": {
"S": "John"
},
"id": {
"N": "1"
}
}
}
```
## 文件
**注意**
[速記語法](cli-usage-shorthand.md)與文件類型不相容。
文件類型用於傳送資料，無需將 JSON 嵌入字串中。文件類型使服務能夠提供任意架構，以便您使用更靈活的資料類型。
這允許在不需要轉義值的情況下傳送 JSON 資料。例如，不使用以下轉義的 JSON 輸入：
```
{"document": "{\"key\":true}"}
```
您可以使用以下文件類型：
```
{"document": {"key": true}}
```
### 文件類型的有效值
由於文件類型的靈活性，有多種有效的值類型。有效值包括下列項目：
**String**
```
--option '"value"'
```
**數字**
```
--option 123
--option 123.456
```
**Boolean**
```
--option true
```
**Null**
```
--option null
```
**Array**
```
--option '["value1", "value2", "value3"]'
--option '["value", 1, true, null, ["key1", 2.34], {"key2": "value2"}]'
```
**物件**
```
--option '{"key": "value"}'
--option '{"key1": "value1", "key2": 123, "key3": true, "key4": null, "key5": ["value3", "value4"], "key6": {"value5": "value6"}'
```
# 在 中使用引號和常值搭配字串 AWS CLI
在 AWS CLI中使用單引號和雙引號的方式主要有兩種。
+ [在包含空格的字串前後使用引號](#cli-usage-parameters-quoting-strings-around)
+ [在字串內使用引號](#cli-usage-parameters-quoting-strings-containing)
## 在包含空格的字串前後使用引號
參數名稱及其值在命令列上以空格分隔。如果字串值包含內嵌空間，則必須以引號括住整個字串，以防止 AWS CLI 將空間錯誤解譯為值和下一個參數名稱之間的分隔符號。您使用的引號類型取決於您執行 AWS CLI 的作業系統。
------
#### [ Linux and macOS ]
使用單引號 `' '`
```
$ aws ec2 create-key-pair --key-name 'my key pair'
```
如需使用引號的詳細資訊，請依據您偏好的 Shell 參閱相關使用者文件。
------
#### [ PowerShell ]
**單引號 (建議使用)**
單引號 `' '` 稱為 `verbatim` 字串。此字串將照您的輸入傳遞至命令，這表示不會傳遞 PowerShell 變數。
```
PS C:\> aws ec2 create-key-pair --key-name 'my key pair'
```
**雙引號**
雙引號 `" "` 稱為 `expandable` 字串。變數可在可擴充的字串中傳遞。
```
PS C:\> aws ec2 create-key-pair --key-name "my key pair"
```
如需使用引號的詳細資訊，請參閱 *Microsoft PowerShell 文件*中的[關於引號規則](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7)。
------
#### [ Windows command prompt ]
使用雙引號 `" "`。
```
C:\> aws ec2 create-key-pair --key-name "my key pair"
```
------
您也可以使用等號 `=` 而非空格來將參數名稱與數值分開。通常只有當參數值的開頭為連字號時，才需要這麼做。
```
$ aws ec2 delete-key-pair --key-name=-mykey
```
## 在字串內使用引號
字串可能包含引號，且您的 Shell 可能需要逸出引號才能使其正常運作。其中一個常見的參數值類型是 JSON 字串。這很複雜，因為其在 JSON 結構中的每個元素名稱和數值前後都包含空格和雙引號 `" "`。您在命令列輸入 JSON 格式參數的方式會因您的作業系統而異。
若要在命令列中使用更進階的 JSON，請考慮使用 `jq` 之類的命令列 JSON 處理器來建立 JSON 字串。如需 `jq` 的詳細資訊，請參閱 *GitHub* 上的 [jq 儲存庫](http://stedolan.github.io/jq/)。
------
#### [ Linux and macOS ]
為了讓 Linux 和 macOS 按字面含義解釋字串，請使用單引號 `' '` 將 JSON 資料結構括住，如以下範例所示。您不需要逸出 JSON 字串中內嵌的雙引號，因為它們會以字面含義處理。由於 JSON 會以單引號括住，因此字串中的任何單引號都需要逸出；為此，我們通常會在單引號前面使用反斜線 `\'`。
```
$ aws ec2 run-instances \
--image-id ami-12345678 \
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
如需使用引號的詳細資訊，請依據您偏好的 Shell 參閱相關使用者文件。
------
#### [ PowerShell ]
使用單引號 `' '` 或雙引號 `" "`。
**單引號 (建議使用)**
單引號 `' '` 稱為 `verbatim` 字串。此字串將照您的輸入傳遞至命令，這表示不會傳遞 PowerShell 變數。
由於 JSON 資料結構包含雙引號，我們建議使用**單**引號 `' '` 將其括住。如果您使用**單**引號，則不需要逸出內嵌在 JSON 字串中的**雙**引號。但在 JSON 結構中，您必須使用反引號 ``` 來逸出每個**單**引號。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
```
**雙引號**
雙引號 `" "` 稱為 `expandable` 字串。變數可在可擴充的字串中傳遞。
如果您使用**雙**引號，則不需要逸出內嵌在 JSON 字串中的**單**引號。但在 JSON 結構中，您必須使用反引號 ``` 來逸出每個**雙**引號，如以下範例所示。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`"DeviceName`":`"/dev/sdb`",`"Ebs`":{`"VolumeSize`":20,`"DeleteOnTermination`":false,`"VolumeType`":`"standard`"}}]"
```
如需使用引號的詳細資訊，請參閱 *Microsoft PowerShell 文件*中的[關於引號規則](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7)。
**警告**
在 PowerShell 傳送命令至 之前 AWS CLI，它會判斷您的命令是使用一般 PowerShell `CommandLineToArgvW` 還是引號規則來解譯。在 PowerShell 使用 `CommandLineToArgvW` 進行處理時，您必須使用反斜線 `\` 逸出字元。
如需 PowerShell 中 `CommandLineToArgvW` 的詳細資訊，請參閱 *Microsoft DevBlogs* 中的 [CommandLineToArgvW 對引號和反斜線的奇怪處理是怎麼回事](https://devblogs.microsoft.com/oldnewthing/20100917-00/?p=12833) (What's up with the strange treatment of quotation marks and backslashes by CommandLineToArgvW)、*Microsoft Docs Blog* 中的[大家都以錯誤方式引用命令列引數](https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way) (Everyone quotes command line arguments the wrong way)，以及 *Microsoft Docs* 中的 [CommandLineToArgvW 函數](https://docs.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw#remarks)。
**單引號**
單引號 `' '` 稱為 `verbatim` 字串。此字串將照您的輸入傳遞至命令，這表示不會傳遞 PowerShell 變數。使用反斜線 `\` 逸出字元。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings '[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]'
```
**雙引號**
雙引號 `" "` 稱為 `expandable` 字串。變數可在 `expandable` 字串中傳遞。對於雙引號字串，您必須在每個引號使用 *`\$1* 逸出兩次，而不是只用反引號。反引號會逸出反斜線，然後使用反斜線做為 `CommandLineToArgvW` 程序的逸出字元。
```
PS C:\> aws ec2 run-instances `
--image-id ami-12345678 `
--block-device-mappings "[{`\"DeviceName`\":`\"/dev/sdb`\",`\"Ebs`\":{`\"VolumeSize`\":20,`\"DeleteOnTermination`\":false,`\"VolumeType`\":`\"standard`\"}}]"
```
**Blob (建議)**
若要繞過 JSON 資料輸入的 PowerShell 引號規則，請使用 Blob 將 JSON 資料直接傳遞至 AWS CLI。如需 Blobs 的詳細資訊，請參閱 [Blob](cli-usage-parameters-types.md#parameter-type-blob)。
------
#### [ Windows command prompt ]
Windows 命令提示要求使用雙引號 `" "` 括住 JSON 資料結構。此外，若要防止命令處理器錯誤解譯 JSON 中內嵌的雙引號，您也必須在 JSON 資料結構本身中逸出 (前面加上反斜線 `\` 字元) 每個雙引號 `"`，如下列範例所示。
```
C:\> aws ec2 run-instances ^
--image-id ami-12345678 ^
--block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]"
```
只有最外面的雙引號不用逸出。
------
# 從 中的檔案載入參數 AWS CLI
有些參數預期檔案名稱為引數， 會從中 AWS CLI 載入資料。其他參數可讓您以在命令列中輸入文字或從檔案讀取的形式指定參數值。無論檔案是必要或選用，您都必須正確編碼檔案， AWS CLI 才能了解該檔案。檔案的編碼必須符合讀取系統的預設地區設定。您可以透過使用 Python `locale.getpreferredencoding()` 方法判斷。
此方法用於載入單一參數的檔案。如需使用單一檔案載入多個參數的資訊，請參閱 [AWS CLI 中的骨架和輸入檔案 AWS CLI](cli-usage-skeleton.md)。
**注意**
根據預設，Windows PowerShell 會將文字輸出為 UTF-16，這會與 JSON 檔案和許多 Linux 系統所使用的 UTF-8 編碼衝突。我們建議您`-Encoding ascii`搭配 PowerShell `Out-File`命令使用 ，以確保 AWS CLI 可以讀取產生的檔案。
**Topics**
+ [如何從檔案載入參數](#cli-usage-parameters-file-how)
+ [二進位檔案](#cli-usage-parameters-file-binary)
+ [遠端檔案](#cli-usage-parameters-file-remote)
+ [將檔案載入為速記語法值](#cli-usage-parameters-file-shorthand)
## 如何從檔案載入參數
從檔案載入參數值有時很方便，而不要嘗試完全以命令列參數值輸入，例如當參數是複雜的 JSON 字串時。若要指定包含數值的檔案，請以下列格式指定檔案 URL。
```
file://complete/path/to/file
```
+ 前兩個斜線「/」字元是規格的一部分。如果所需的路徑以「/」開頭，則結果為三個斜線字元：`file:///folder/file`。
+ 此 URL 提供檔案的路徑，該檔案包含實際的參數內容。
+ 使用帶有空格或特殊字符的檔案時，請遵循您終端適用的[引用和逸出規則](cli-usage-parameters-quoting-strings.md)。
**注意**
對於已經預期 URL 的參數，例如識別 CloudFormation 範本 URL 的參數，此行為會自動停用。您也可以在 AWS CLI 組態檔案中停用 [`cli_follow_urlparam`](cli-configure-files.md#cli-config-cli_follow_urlparam)設定來停用此行為。
在下列範例中，檔案路徑是以相對於目前的工作目錄來解譯。
------
#### [ Linux or macOS ]
```
// Read from a file in the current directory
$ aws ec2 describe-instances --filters file://filter.json
// Read from a file in /tmp
$ aws ec2 describe-instances --filters file:///tmp/filter.json
// Read from a file with a filename with whitespaces
$ aws ec2 describe-instances --filters 'file://filter content.json'
```
------
#### [ Windows command prompt ]
```
// Read from a file in C:\temp
C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json
// Read from a file with a filename with whitespaces
C:\> aws ec2 describe-instances --filters "file://C:\temp\filter content.json"
```
------
`file://` 前綴選項支援 Unix 風格的擴展，包括「`~/`」、「`./`」和「`../`」。在 Windows 上，「`~/`」表達式擴展到您的使用者目錄，儲存在 `%USERPROFILE%` 環境變數中。例如，在 Windows 10 中，通常在 `%USERPROFILE%` 下有一個使用者目錄。
您仍然必須逸出內嵌為其他 JSON 文件數值的 JSON 文件。
```
$ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json
```
**attributes.json**
```
{
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"
}
```
## 二進位檔案
對於以二進位資料作為參數的命令，使用 `fileb://` 前綴所指定的資料是二進位內容。接受二進位資料的命令包括：
+ **`aws ec2 run-instances:`** `--user-data` 參數。
+ **`aws s3api put-object:`** `--sse-customer-key` 參數。
+ **`aws kms decrypt:`** `--ciphertext-blob` 參數。
以下範例使用 Linux 命令列工具產生二進位 256 位元 AES 金鑰，然後將其提供給 Amazon S3 來加密上傳的檔案伺服器端。
```
$ dd if=/dev/urandom bs=1 count=32 > sse.key
32+0 records in
32+0 records out
32 bytes (32 B) copied, 0.000164441 s, 195 kB/s
$ aws s3api put-object \
--bucket amzn-s3-demo-bucket \
--key test.txt \
--body test.txt \
--sse-customer-key fileb://sse.key \
--sse-customer-algorithm AES256
{
"SSECustomerKeyMD5": "iVg8oWa8sy714+FjtesrJg==",
"SSECustomerAlgorithm": "AES256",
"ETag": "\"a6118e84b76cf98bf04bbe14b6045c6c\""
}
```
## 遠端檔案
AWS CLI 也支援使用 `http://`或 `https://` URL，從託管在網際網路上的檔案載入參數。以下範例參考存放在 Amazon S3 儲存貯體中的檔案。這使您可以存取任何電腦地參數檔案，但需要將容器放在可公開存取的位置。
```
$ aws ec2 run-instances \
--image-id ami-12345678 \
--block-device-mappings http://amzn-s3-demo-bucket.s3.amazonaws.com/filename.json
```
前面的範例假設檔案 `filename.json` 包含以下 JSON 資料。
```
[
{
"DeviceName": "/dev/sdb",
"Ebs": {
"VolumeSize": 20,
"DeleteOnTermination": false,
"VolumeType": "standard"
}
}
]
```
關於參考包含 JSON 格式參數的檔案的另一個範例，請參閱 [將 IAM 受管政策連接至使用者](cli-services-iam.md#cli-services-iam-policy)。
## 將檔案載入為速記語法值
使用值較大或複雜的速記語法時，通常更容易將檔案載入為值。若要將檔案載入為速記語法值，格式會稍微變更。不是 `key=value`，您將使用 `@=` 運算子，而非 `=` 運算子。`@=` 表示 AWS CLI 應將該值讀為檔案路徑，而不是字串。下列範例會示範金鑰-值對如何為其值載入檔案。
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
下列範例會示範為 `aws rolesanywhere create-trust-anchor` 命令載入憑證檔案。
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
如需速記語法的詳細資訊，請參閱 [在 中使用速記語法 AWS CLI](cli-usage-shorthand.md)。
# AWS CLI 中的骨架和輸入檔案 AWS CLI
大多數 AWS CLI 命令都接受從檔案匯入參數輸入。這些範本可以使用 `generate-cli-skeleton` 選項產生，然後使用 `--cli-input-json` 參數匯入。
**Topics**
+ [關於骨 AWS CLI 架和輸入檔案](#cli-usage-skeleton-about)
+ [產生和匯入命令骨架](#cli-usage-skeleton-generate)
+ [結合輸入檔案和命令列參數](#cli-usage-skeleton-combine)
## 關於骨 AWS CLI 架和輸入檔案
大多數 AWS Command Line Interface (AWS CLI) 命令都支援使用 `--cli-input-json` 參數接受來自檔案的參數輸入。
這些相同命令使用 `--generate-cli-skeleton` 參數，以您能夠編輯和填入的所有參數來產生 JSON 格式的檔案。然後，您可以執行命令搭配 `--cli-input-json` 參數，以指向要填入的檔案。
**重要**
自訂 AWS CLI 命令，例如[`aws s3`命令](https://docs.aws.amazon.com/cli/v1/reference/s3/index.html)不支援本主題中所述的 `--generate-cli-skeleton`或 `--cli-input-json` 參數。若要檢查特定命令是否支援這些參數，請針對您要使用的命令執行 [`help` 命令](cli-usage-help.md#cli-usage-help-command)，或參閱[AWS CLI 版本 1 參考指南](https://docs.aws.amazon.com/cli/v1/reference/)。
`--generate-cli-skeleton` 會產生並顯示參數範本，您可以在命令上自訂該範本並用作輸入。產生的範本包含命令支援的所有參數。
`--generate-cli-skeleton` 參數接受下列其中一個數值：
+ `input` – 產生的範本包括所有格式化為 JSON 的輸入參數。這是預設值。
+ `output` – 產生的範本包括所有 JSON 格式的輸出參數。
由於 基本上 AWS CLI 是圍繞服務 API 的「包裝函式」，因此骨架檔案會要求您依其基礎 API 參數名稱來參考所有參數。這可能與 AWS CLI 參數名稱不同。例如，名為 的 AWS CLI 參數`user-name`可能會對應到名為 AWS 的服務 API 參數 `UserName`（請注意已變更的大寫和遺失破折號）。建議您使用 `--generate-cli-skeleton` 選項，以「正確」參數名稱產生範本，以免發生錯誤。您可以參考該服務的《API 參考指南》，以查看預期的參數名稱。您可以從範本刪除任何非必要且不想為其提供數值的參數。
例如，如果您執行以下命令，其會為 Amazon Elastic Compute Cloud (Amazon EC2) 命令 **run-instances** 產生參數範本。
------
#### [ JSON ]
下列範例顯示如何使用 `--generate-cli-skeleton` 參數的預設值 (`input`) 生產格式化的 JSON 範本。
```
$ aws ec2 run-instances --generate-cli-skeleton
```
```
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
```
------
## 產生和匯入命令骨架
**若要產生和使用參數骨架檔案**
1. 執行命令搭配 `--generate-cli-skeleton` 參數，產生 JSON，並將輸出導向至檔案以便儲存。
------
#### [ JSON ]
```
$ aws ec2 run-instances --generate-cli-skeleton input > ec2runinst.json
```
------
1. 在文字編輯器中開啟參數骨架檔案，移除您不需要的任何參數。例如，您可以將範本剔除為下列內容。移除不需要的元素之後，請確認檔案仍是有效的 JSON 。
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "",
"KeyName": "",
"SecurityGroups": [
""
],
"InstanceType": "",
"Monitoring": {
"Enabled": true
}
}
```
------
在此範例中，我們會保留設定為 `true` 的 `DryRun` 參數，以便使用 Amazon EC2 試轉功能。此功能可讓您安全地測試命令，而不必實際建立或修改任何資源。
1. 使用適合您方案的數值，填入其餘數值。在這個範例中，我們提供 Amazon Machine Image (AMI) 的執行個體類型、金鑰名稱、安全群組和識別符以供使用。此範例假設預設值 AWS 區域。AMI `ami-dfc39aef` 是託管於 `us-west-2` 區域中的 64 位元 Amazon Linux 映像。如果使用不同的區域，您必須 [找到要使用的正確 AMI ID](https://aws.amazon.com/amazon-linux-ami/)。
------
#### [ JSON ]
```
{
"DryRun": true,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
1. 使用 `file://` 前綴將完整的範本檔案傳遞到 `--cli-input-json`參數，以使用完成的參數執行命令。會 AWS CLI 解譯相對於您目前工作目錄的路徑。下列範例會在目前的工作目錄中 AWS CLI 尋找 檔案。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
試轉錯誤表示 JSON 正確產生且參數值有效。如果在輸出中報告其他問題，請修復它們並重複先前步驟，直到顯示「`Request would have succeeded`」訊息為止。
1. 現在您可以將 `DryRun` 參數設定為 `false`，以停用試轉。
------
#### [ JSON ]
```
{
"DryRun": false,
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
1. 執行命令，`run-instances` 會實際啟動 Amazon EC2 執行個體並顯示成功啟動產生的詳細資訊。輸出的格式是由 `--output` 參數控制，與輸入參數範本的格式分開。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
## 結合輸入檔案和命令列參數
輸入檔案可用於所有參數，也可以與 AWS CLI中指定的參數結合。您可以將此功能用於在輸入檔案中經常重複使用的設定，同時將個別設定保留在命令本身。
下列 `aws ec2 run-instances` 範例會結合使用輸入檔案和參數。我們提供執行個體類型、金鑰名稱、安全群組、Amazon Machine Image (AMI) 的識別符，以供使用並擔任預設值 AWS 區域。AMI `ami-dfc39aef` 是託管於 `us-west-2` 區域中的 64 位元 Amazon Linux 映像。如果使用不同的區域，您必須 [找到要使用的正確 AMI ID](https://aws.amazon.com/amazon-linux-ami/)。
------
#### [ JSON ]
JSON 檔案的內容：
```
{
"ImageId": "ami-dfc39aef",
"KeyName": "mykey",
"SecurityGroups": [
"my-sg"
],
"InstanceType": "t2.micro",
"Monitoring": {
"Enabled": true
}
}
```
------
下列範例使用輸入檔案並搭配 `--dry-run` 參數，來執行命令的停用試轉，以確認您是否具有所需的許可，並已使用有效的值填入檔案。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --dry-run
```
```
A client error (DryRunOperation) occurred when calling the RunInstances operation: Request would have succeeded, but DryRun flag is set.
```
------
以下範例接著會使用相同的輸入檔案，但使用 `--no-dry-run` 參數完整執行命令。
------
#### [ JSON ]
```
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json --no-dry-run --output json
```
```
{
"OwnerId": "123456789012",
"ReservationId": "r-d94a2b1",
"Groups": [],
"Instances": [
...
```
------
# 在 中使用速記語法 AWS CLI
AWS Command Line Interface (AWS CLI) 可以接受 JSON 格式的許多選項參數。不過，在命令列輸入大型 JSON 清單或結構可能會變得很冗長。為了簡化此作業， AWS CLI 也支援速記語法，相較於使用完整的 JSON 格式，可讓您更輕鬆地呈現選項參數。
**Topics**
+ [具有金鑰-值對的結構參數](#shorthand-structure-parameters)
+ [將檔案載入為速記語法值](#shorthand-files)
+ [搭配 使用速記語法 AWS CLI](#shorthand-list-parameters)
## 具有金鑰-值對的結構參數
中的速記語法 AWS CLI 可讓使用者更輕鬆地輸入平坦的參數 （非巢狀結構）。格式為以逗號分隔的鍵值對清單。請務必使用您的終端機適用的[引用](cli-usage-parameters-quoting-strings.md)和轉義規則，因為速記語法是字串。
------
#### [ Linux or macOS ]
```
--option key1=value1,key2=value2,key3=value3
```
等同於下列 JSON 格式的範例。
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
#### [ Windows ]
```
--option "key1=value1,key2=value2,key3=value3"
```
等同於下列 JSON 格式的範例。
```
--option '{"key1":"value1","key2":"value2","key3":"value3"}'
```
------
每個逗號分隔的金鑰/數值對之間不能有空白字元。以下範例為 Amazon DynamoDB `update-table` 命令，其包含以速記語法指定的 `--provisioned-throughput` 選項。
```
$ aws dynamodb update-table \
--provisioned-throughput ReadCapacityUnits=15,WriteCapacityUnits=10 \
--table-name MyDDBTable
```
這等同於下列 JSON 格式的範例。
```
$ aws dynamodb update-table \
--provisioned-throughput '{"ReadCapacityUnits":15,"WriteCapacityUnits":10}' \
--table-name MyDDBTable
```
## 將檔案載入為速記語法值
當值較大或複雜時，通常更容易載入做為值。若要將檔案載入為速記語法值，格式會稍微變更。不是 `key=value`，您將使用 `@=` 運算子，而非 `=` 運算子。`@=` 表示 AWS CLI 值應該讀取為檔案路徑，而不是字串。以速記語法載入檔案時，一般的 [AWS CLI 檔案格式規則適用](cli-usage-parameters-file.md)。下列範例會示範金鑰-值對如何為其值載入檔案。
------
#### [ Linux or macOS ]
```
--option key@=file://template.txt
```
------
#### [ Windows ]
```
--option "key1@=file://template.txt"
```
------
下列範例會示範為 `aws rolesanywhere create-trust-anchor` 命令載入憑證檔案。
```
$ aws rolesanywhere create-trust-anchor --name TrustAnchor \
--source sourceData={x509CertificateData@=file://root-ca.crt},sourceType="CERTIFICATE_BUNDLE" \
--enabled
```
## 搭配 使用速記語法 AWS CLI
您可以用兩種方式指定清單形式中的輸入參數：JSON 或速記。 AWS CLI 的速記語法易於傳入具有數字、字串或非巢狀結構的清單中。
基本格式如下所示，清單中的數值以單一空格分隔。
```
--option value1 value2 value3
```
這等同於下列 JSON 格式的範例。
```
--option '[value1,value2,value3]'
```
如同先前所述，您可以使用速記語法來指定數字清單、字串清單或非巢狀結構的清單。以下是 Amazon Elastic Compute Cloud (Amazon EC2) `stop-instances` 命令的範例，其中 `--instance-ids` 選項的輸入參數 (字串清單) 以速記語法指定。
```
$ aws ec2 stop-instances \
--instance-ids i-1486157a i-1286157c i-ec3a7e87
```
這等同於下列 JSON 格式的範例。
```
$ aws ec2 stop-instances \
--instance-ids '["i-1486157a","i-1286157c","i-ec3a7e87"]'
```
下列範例顯示 Amazon EC2 `create-tags` 命令，其中 `--tags` 選項採用非巢狀結構的清單。`--resources` 選項指定要標記之執行個體的 ID。
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3
```
這等同於下列 JSON 格式的範例。為確保易讀性，JSON 參數以多行文字編寫。
```
$ aws ec2 create-tags \
--resources i-1286157c \
--tags '[
{"Key": "My1stTag", "Value": "Value1"},
{"Key": "My2ndTag", "Value": "Value2"},
{"Key": "My3rdTag", "Value": "Value3"}
]'
```