# AWS CLI 中的通用参数类型
<a name="cli-usage-parameters-types"></a>

本节介绍一些通用参数类型以及典型的所需格式。

如果您不知道如何设置特定命令的参数格式，请在命令名称后输入 **help** 来查看帮助。每个子命令的帮助均包括一个选项的名称和描述。该选项的参数类型在括号中列出。有关查看帮助的更多信息，请参阅 [在 AWS CLI 中获取帮助和资源](cli-usage-help.md)。

**Topics**
+ [

## 字符串
](#parameter-type-string)
+ [

## Timestamp
](#parameter-type-timestamp)
+ [

## 列表
](#parameter-type-list)
+ [

## 布尔值
](#parameter-type-boolean)
+ [

## 整数
](#parameter-type-integer)
+ [

## 二进制/Blob（二进制大型对象）和流式传输 Blob
](#parameter-type-blobs)
+ [

## 映射
](#parameter-type-map)
+ [

## 文档
](#parameter-type-document)

## 字符串
<a name="parameter-type-string"></a>

字符串参数可以包含 [ASCII](https://wikipedia.org/wiki/ASCII) 字符集中的字母数字字符、符号和空格。包含空格的字符串必须用引号引起来。建议您不要使用标准空格字符以外的符号或空格，并遵循终端的[引用规则](cli-usage-parameters-quoting-strings.md)，以防止出现意外结果。

一些字符串参数可接受来自文件的二进制数据。有关示例，请参阅[二进制文件](cli-usage-parameters-file.md#cli-usage-parameters-file-binary)。

## Timestamp
<a name="parameter-type-timestamp"></a>

时间戳根据 [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 纪元时间](https://wikipedia.org/wiki/Unix_time)，表示自 1970 年 1 月 1 日午夜 (UTC) 以来经历的秒数。

预设情况下，AWS CLI 版本 2 会将所有***响应*** DateTime 值转换为 ISO 8601 格式。

您可以使用 `cli\$1timestamp\$1format` 文件设置来设置时间戳格式。

## 列表
<a name="parameter-type-list"></a>

以空格分隔的一个或多个字符串。如果任何字符串项目包含空格，则必须用引号括起该项目。遵循您终端的[引号规则](cli-usage-parameters-quoting-strings.md)以防止出现意外结果。

```
$ aws ec2 describe-spot-price-history --instance-types m1.xlarge m1.medium
```

## 布尔值
<a name="parameter-type-boolean"></a>

打开或关闭某一选项的二进制标志。例如，`ec2 describe-spot-price-history` 有一个布尔 `--dry-run` 参数，如果指定该参数，则针对服务验证查询而不实际运行查询。

```
$ aws ec2 describe-spot-price-history --dry-run
```

输出指示命令格式是否正确。此命令还包含一个 `--no-dry-run` 参数版本，可以用来显式指示命令应正常运行。不过不是必须包含此参数，因为这是默认行为。

## 整数
<a name="parameter-type-integer"></a>

无符号整数。

```
$ aws ec2 describe-spot-price-history --max-items 5
```

## 二进制/Blob（二进制大型对象）和流式传输 Blob
<a name="parameter-type-blobs"></a>

在 AWS CLI 中，您可以将二进制值作为字符串直接在命令行上传递。共有两种类型的 blob：
+ [Blob](#parameter-type-blob)
+ [流式 blob](#parameter-type-streaming-blob)

### Blob
<a name="parameter-type-blob"></a>

要将值传递给类型为 `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
```

**注意**  
为了向后兼容，您可以使用 `file://` 前缀。根据文件设置 `cli\$1binary\$1format` 或 `--cli-binary-format` 命令行选项，可以使用两种格式：  
AWS CLI 版本 2 的默认值。如果设置的值为 `base64`，则使用 `file://` 前缀引用的文件将被作为 base64 编码文本进行处理。
AWS CLI 版本 1 的默认值。如果设置的值为 `raw-in-base64-out`，则使用 `file://` 前缀引用的文件会作为文本进行读取，然后 AWS CLI 尝试将其编码为二进制。
有关更多信息，请参阅文件设置 `cli\$1binary\$1format` 或 `--cli-binary-format` 命令行选项。

### 流式 Blob
<a name="parameter-type-streaming-blob"></a>

`aws cloudsearchdomain upload-documents` 等流式 Blob 不使用前缀。相反，流式传输 blob 参数使用直接文件路径进行格式化。以下示例对于 `aws cloudsearchdomain upload-documents` 命令使用直接文件路径 `document-batch.json`：

```
$ aws cloudsearchdomain upload-documents \
    --endpoint-url https://doc-my-domain.us-west-1.cloudsearch.amazonaws.com \
    --content-type application/json \
    --documents document-batch.json
```

## 映射
<a name="parameter-type-map"></a>

使用 JSON 或 CLI 的[速记语法](cli-usage-shorthand.md)指定的一系列密钥值对。以下 JSON 示例使用 map 参数 `--key` 从名为 *my-table* 的 Amazon DynamoDB 表中读取项目。此参数在嵌套的 JSON 结构中指定名为 *id* 且数值为 *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"
        }
    }
}
```

## 文档
<a name="parameter-type-document"></a>

**注意**  
[速记语法](cli-usage-shorthand.md)与文档类型不兼容。

文档类型用于发送数据，无需在字符串中嵌入 JSON。文档类型使服务能够提供任意架构，以便您使用更灵活的数据类型。

这使得无需对值转义，即可发送 JSON 数据。例如，不使用以下转义的 JSON 输入：

```
{"document": "{\"key\":true}"}
```

您可以使用以下文档类型：

```
{"document": {"key": true}}
```

### 文档类型的有效值
<a name="parameter-type-document-valid"></a>

由于文档类型本身多种多样，因此存在多个有效值类型。有效值包括：

**字符串**  

```
--option '"value"'
```

**数字**  

```
--option 123
--option 123.456
```

**布尔值**  

```
--option true
```

**Null**  

```
--option null
```

**数组**  

```
--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"}'
```