AWS Command Line Interface
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

为 AWS CLI 指定参数值

AWS Command Line Interface (AWS CLI) 中使用的很多参数都是简单的字符串或数值,如下面示例中的 my-key-pair 密钥对名称。

$ aws ec2 create-key-pair --key-name my-key-pair

没有任何空格字符的字符串可以用引号引起来。但是,必须将包含一个或多个空格字符的字符串用引号引起来。在 Linux、macOS 或 Unix PowerShell 中使用单引号 (' ')。在 Windows 命令提示符中使用双引号 (" "),如以下示例所示。

PowerShell,Linux, OS X, or Unix

$ aws ec2 create-key-pair --key-name 'my key pair'

Windows 命令提示符

C:\> aws ec2 create-key-pair --key-name "my key pair"

您可以用等号 (=) 而不是空格将参数名称和值分开。这通常仅在参数的值以连字符开头时有必要。

$ aws ec2 delete-key-pair --key-name=-mykey

通用参数类型

本节介绍一些通用参数类型以及典型的所需格式。如果您不知道如何设置特定命令的参数格式,请在命令名称后键入 help 来查看帮助,例如:

$ aws ec2 describe-spot-price-history help

每个子命令的帮助都介绍了其功能、选项、输出和示例。选项部分包括每个选项的名称和说明,并在括号中给出了选项的参数类型。

String – 字符串参数可以包含 ASCII 字符集中的字母数字字符、符号和空格。包含空格的字符串必须用引号引起来。我们建议您不要使用标准空格字符以外的符号或空格,因为它可能会导致意外结果。

一些字符串参数可接受来自文件的二进制数据。有关示例,请参阅二进制文件

Timestamp – 时间戳根据 ISO 8601 标准设置格式。这些有时称为“DateTime”或“Date”参数。

$ aws ec2 describe-spot-price-history --start-time 2014-10-13T19:00:00Z

可接受的格式包括:

  • YYYY-MM-DDThh:mm:ss.sssTZD (UTC),例如,2014-10-01T20:30:00.000Z

  • YYYY-MM-DDThh:mm:ss.sssTZD(带偏移量),例如,2014-10-01T12:30:00.000-08:00

  • YYYY-MM-DD,例如,2014-10-01

  • 以秒为单位的 Unix 时间,例如 1412195400。这有时称为 Unix 纪元时间,表示自 1970 年 1 月 1 日午夜 (UTC) 以来经历的秒数。

List – 以空格分隔的一个或多个字符串。如果任何字符串项目包含空格,则必须用引号括起该项目。

$ 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

Blob – 二进制对象。Blob 参数采用包含二进制数据的本地文件的路径。此路径不应包含任何协议标识符,例如 http://file://。指定的路径被解释为相对于当前工作目录。

例如,适用于 aws s3api put-object--body 参数是一个 blob。

$ aws s3api put-object --bucket my-bucket --key testimage.png --body /tmp/image.png

Map – 使用 JSON 或 CLI 的速记语法指定的一系列密钥值对。以下 JSON 示例使用 map 参数 --key 从名为 my-table 的 Amazon DynamoDB 表中读取项目。此参数在嵌套的 JSON 结构中指定名为 id 且数值为 1 的主键。

$ aws dynamodb get-item --table-name my-table --key '{"id": {"N":"1"}}' { "Item": { "name": { "S": "John" }, "id": { "N": "1" } } }

对参数使用 JSON

JSON 对于指定复杂的命令行参数非常有用。例如,下面的命令列出实例类型为 m1.smallm1.medium 并在 us-west-2c 可用区中的所有 Amazon EC2 实例。

$ aws ec2 describe-instances --filters "Name=instance-type,Values=t2.micro,m1.medium" "Name=availability-zone,Values=us-west-2c"

或者,您可以将筛选条件的等效列表指定为 JSON 数组。方括号用于创建以逗号分隔的 JSON 对象的数组。每个对象均为以逗号分隔开的密钥值对列表(在此实例中,“Name”和“Values”都是密钥)。

“Values”密钥右侧的值本身就是数组。即使数组只包含一个值字符串,也是必需的。

[ { "Name": "instance-type", "Values": ["t2.micro", "m1.medium"] }, { "Name": "availability-zone", "Values": ["us-west-2c"] } ]

但是,仅在指定一个以上的筛选器时需要最外层的括号。上一个命令的 JSON 格式的单个筛选器版本如下所示。

$ aws ec2 describe-instances --filters '{"Name": "instance-type", "Values": ["t2.micro", "m1.medium"]}'

对于某些操作,您必须将数据格式设置为 JSON。例如,要向 --block-device-mappings 命令中的 ec2 run-instances 参数传递参数,您需要将块储存设备信息的格式设置为 JSON。

此示例显示的 JSON 指定一个在启动实例时在 /dev/sdb 中映射的 20 GiB Amazon Elastic Block Store (Amazon EBS) 设备。

{ "DeviceName": "/dev/sdb", "Ebs": { "VolumeSize": 20, "DeleteOnTermination": false, "VolumeType": "standard" } }

要连接多个设备,请在数组中列出对象,如下一个示例中所示。

[ { "DeviceName": "/dev/sdb", "Ebs": { "VolumeSize": 20, "DeleteOnTermination": false, "VolumeType": "standard" } }, { "DeviceName": "/dev/sdc", "Ebs": { "VolumeSize": 10, "DeleteOnTermination": true, "VolumeType": "standard" } } ]

您可以直接在命令行输入 JSON(请参阅将引号和字符串结合使用),也可以将它保存为一个从命令行引用的文件(请参阅从文件加载参数)。

当传入大块数据时,先将 JSON 保存为一个文件,然后从命令行引用它可能更为简单。文件中的 JSON 数据更容易读取、编辑和与他人共享。后面的部分将介绍这一方法。

有关 JSON 的更多信息,请参阅 JSON.orgWikipedia 的 JSON 条目RFC4627 - JSON 的应用程序/json 媒体类型

将引号和字符串结合使用

在命令行中输入 JSON 格式参数的方式因操作系统而异。

Linux、macOS 或 Unix

使用单引号 (' ') 括住 JSON 数据结构,如下例所示:

$ aws ec2 run-instances --image-id ami-12345678 --block-device-mappings '[{"DeviceName":"/dev/sdb","Ebs":{"VolumeSize":20,"DeleteOnTermination":false,"VolumeType":"standard"}}]'
PowerShell

PowerShell 需要单引号 (' ') 括住 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\"}}]'
Windows 命令提示符

Windows 命令提示符要求使用双引号 (" ") 括住 JSON 数据结构。然后,您必须对 JSON 数据结构中的每个双引号 (") 本身进行转义(前面有一个反斜杠 [ \ ] 字符),如下例所示:

C:\> aws ec2 run-instances --image-id ami-12345678 --block-device-mappings "[{\"DeviceName\":\"/dev/sdb\",\"Ebs\":{\"VolumeSize\":20,\"DeleteOnTermination\":false,\"VolumeType\":\"standard\"}}]"

只有最外层双引号不进行转义。

如果参数值本身是一个 JSON 文档,请对该嵌入 JSON 文档中的引号进行转义。例如,attributeaws sqs create-queue 参数可以使用 RedrivePolicy 键。--attributes 参数取值为一个 JSON 文档,而该文档包含 RedrivePolicy,后者也将 JSON 文档作为其值。嵌入到外层 JSON 的内层 JSON 必须进行转义。

$ aws sqs create-queue --queue-name my-queue --attributes '{ "RedrivePolicy":"{\"deadLetterTargetArn\":\"arn:aws-cn:sqs:us-west-2:0123456789012:deadletter\", \"maxReceiveCount\":\"5\"}"}'

从文件加载参数

有些参数需要文件名作为变量,AWS CLI 将从这些变量中加载数据。其他参数允许您将参数值指定为在命令行上键入的文本或从文件中读取的文本。无论文件是必需还是可选的,该文件都必须正确编码才能被 AWS CLI 理解。该文件的编码必须与读取系统的默认区域设置相匹配。这可以通过使用 Python locale.getpreferredencoding() 方法来确定。

注意

默认情况下,Windows PowerShell 将文本输出为 UTF-16,这与许多 Linux 系统使用的 UTF-8 冲突。我们建议您将 -Encoding ascii 与 PowerShell Out-File 命令一起使用,以确保生成的文件可以被 AWS CLI 读取。

有时,从文件加载参数值(而不是尝试将其全部键入为命令行参数值)很方便,例如当参数为复杂的 JSON 字符串时。要指定包含该值的文件,请按以下格式指定文件 URL:

file://complete/path/to/file

前两个斜杠“/”字符是规范的一部分。如果所需的路径以“/”开头,则结果为三个斜杠字符:file:///folder/file

URL 提供包含实际参数内容的文件的路径。

注意

对于本就要求指定 URI 的参数(例如标识 AWS CloudFormation 模板 URI 的参数),将自动禁用该行为。

您也可以通过将以下行添加到 CLI 配置文件来自行禁用该行为:

cli_follow_urlparam = false

以下示例中的文件路径被解读为相对于当前工作目录。

Linux, OS X, or Unix

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

Windows

// Read from a file in C:\temp C:\> aws ec2 describe-instances --filters file://C:\temp\filter.json

file:// 前缀选项支持包含“~/”、“./”和“../”的 Unix 式扩展。在 Windows 上,“~/”表达式将展开到您的用户目录(存储在 %USERPROFILE% 环境变量中)。例如,在 Windows 10 上,您通常在 C:\Users\User Name\ 下有一个用户目录。

作为另一个 JSON 文档的值嵌入的 JSON 文档仍必须进行转义。

$ aws sqs create-queue --queue-name my-queue --attributes file://attributes.json

attributes.json

{ "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws-cn: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 my-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 从 Internet 上托管的文件中加载参数。下面的示例引用存储在 Amazon S3 存储桶中的一个文件。这将允许您从任何计算机访问参数文件,但它的确要求容器可公开访问。

$ aws ec2 run-instances --image-id ami-12345678 --block-device-mappings http://my-bucket.s3.amazonaws.com/filename.json

前面的示例假定 filename.json 文件包含以下 JSON 数据。

[ { "DeviceName": "/dev/sdb", "Ebs": { "VolumeSize": 20, "DeleteOnTermination": false, "VolumeType": "standard" } } ]

有关引用包含更复杂 JSON 格式参数的文件的更多示例,请参阅将 IAM 托管策略附加到 IAM 用户