本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
重大更改 – 从 AWS CLI 版本 1 迁移到版本 2
本主题介绍 AWS CLI 版本 1 和 AWS CLI 版本 2 之间行为的变化,这些变化可能要求您对脚本或命令进行更改,以便在版本 2 中获得与版本 1 中相同的行为。
主题
- AWS CLI 版本 2 现在使用环境变量设置文本文件编码
- 默认情况下,AWS CLI 版本 2 现在将二进制参数作为 base64 编码字符串进行传递
- AWS CLI 版本 2 改进了执行分段复制时对文件属性和标签的 Amazon S3 处理
- AWS CLI 版本 2 不再自动检索 http:// 或 https:// URL 以获取参数
- 默认情况下,AWS CLI 版本 2 会对所有输出使用分页程序。
- AWS CLI 版本 2 现在返回 ISO 8601 格式的所有时间戳输出值。
- AWS CLI 版本 2 改进了对 AWS CloudFormation 部署的处理,从而导致不会发生任何更改
- AWS CLI 版本 2 以更一致的方式使用 Amazon S3 密钥
- AWS CLI 版本 2 会为 us-east-1 区域使用正确的 Amazon S3 区域终端节点
- 默认情况下,AWS CLI 版本 2 使用区域 AWS STS 终端节点
- AWS CLI 版本 2 将 ecr get-login 替换为 ecr get-login-password
- AWS CLI 版本 2 对插件的支持会不断变化
- AWS CLI 版本 2 不再支持“隐藏”别名
AWS CLI 版本 2 现在使用环境变量设置文本文件编码
默认情况下,文本文件使用与已安装的区域设置相同的编码。要将文本文件的编码设置为不同于区域设置,请使用 AWS_CLI_FILE_ENCODING
环境变量。下面的示例将 CLI 设置为在 Windows 上使用 UTF-8
打开文本文件。
AWS_CLI_FILE_ENCODING=UTF-8
有关更多信息,请参阅用于配置 AWS CLI 的环境变量。
默认情况下,AWS CLI 版本 2 现在将二进制参数作为 base64 编码字符串进行传递
AWS CLI 版本 1 并不总是能够在不需要一些中间处理的情况下,很轻松地将二进制参数从一个命令的输出传递到另一个命令的输入。有些命令需要 base64
默认情况下,AWS CLI 版本 2 现在将所有二进制输入和二进制输出参数作为 base64 编码字符串进行传递。需要二进制输入的参数在文档中将其类型指定为 blob
(二进制大型对象)。要将二进制数据作为文件传递给 CLI 参数,您可以通过 AWS CLI 版本 2 指定使用以下前缀的文件:
-
file://
– AWS CLI 会将文件内容作为 base64 编码文本进行处理。例如:--some-param file://~/my/path/file-with-base64.txt
-
fileb://
– AWS CLI 会将文件内容作为未编码的二进制文件进行处理。例如:--some-param fileb://~/my/path/file-with-raw-binary.bin
您可以通过在 ~/.aws/config
文件中为配置文件指定以下行来告诉 AWS CLI 版本 2 恢复到该 AWS CLI 版本 1 行为。
cli_binary_format=raw-in-base64-out
您还可以通过在命令行中包含参数 --cli-binary-format
raw-in-base64-out
来恢复单个命令的设置,覆盖活动配置文件设置。
如果您恢复为 AWS CLI 版本 1 行为,并使用 file://
或 fileb://
指定二进制参数文件,AWS CLI 会将文件内容作为未编码的原始二进制文件来处理。
AWS CLI 版本 2 改进了执行分段复制时对文件属性和标签的 Amazon S3 处理
当您使用 aws s3
命名空间中的 AWS CLI 版本 1 版本命令将文件从一个 Amazon S3 存储桶位置复制到另一个 Amazon S3 存储桶位置,并且该操作使用分段复制时,源对象中的文件属性不会被复制到目标对象。
现在,在默认情况下,s3
命名空间中执行分段复制的 AWS CLI 版本 2 命令会将所有标签和以下属性集从源副本传输到目标副本:content-type
、content-language
、content-encoding
、content-disposition
、cache-control
、expires
和 metadata
。
这可能会导致对 Amazon S3 终端节点进行其他 AWS API 调用,而在使用 AWS CLI 版本 1 时,将不会进行这些调用。这些调用可能包括:HeadObject
、GetObjectTagging
和 PutObjectTagging
。
如果需要在 AWS CLI 版本 2 命令中更改此默认行为,请使用 --copy-props
参数指定以下选项之一:
-
default – 默认值。指定该复制包含附加到源对象的所有标签以及用于非分段复制的
--metadata-directive
参数所包含的属性:content-type
、content-language
、content-encoding
、content-disposition
、cache-control
、expires
和metadata
。 -
metadata-directive – 指定该复制仅包含用于非分段复制的
--metadata-directive
参数所包含的属性。它不会复制任何标签。 -
none – 指定该复制不包含源对象中的任何属性。
AWS CLI 版本 2 不再自动检索 http://
或 https://
URL 以获取参数
当参数值以 http://
或 https://
开头,然后使用返回的内容作为参数的值时,AWS CLI 版本 2 不再执行 GET 操作。如果您需要检索 URL 并将从该 URL 读取的内容作为参数值传递,我们建议您使用
curl
或类似的工具将 URL 的内容下载到本地文件。然后使用 file://
语法读取该文件的内容,并将其用作参数的值。
例如,以下命令不再尝试检索在 http://www.google.com
中找到的页面的内容,并将这些内容作为参数传递。相反,它将文字文本字符串 https://google.com
作为参数传递。
$
aws ssm put-parameter --value http://www.google.com --name prod.microservice1.db.secret --type String 2
如果您确实想要检索 Web URL 的内容并将其用作参数,则可以在版本 2 中执行以下操作。
$
curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json$
aws iam put-role-policy --policy-document file://./mypolicyfile.json --role-name MyRole --policy-name MyReadOnlyPolicy
在前面的示例中,-o
参数指示 curl
将文件保存在与源文件同名的当前文件夹中。第二个命令检索该下载文件的内容,并将内容作为 --policy-document
的值传递。
默认情况下,AWS CLI 版本 2 会对所有输出使用分页程序。
默认情况下,AWS CLI 版本 2 会通过操作系统的默认分页程序返回所有输出。默认情况下,此程序是 Linux 和 macOS 上的 less
more
~/.aws/config
文件中配置 AWS_PAGER
环境变量或 cli_pager
设置,并指定要使用的命令。您可以指定搜索路径中的命令,或者指定计算机上可用的任何命令的完整路径和文件名。
要完全禁用外部分页程序,您可以将该变量设置为空字符串,如以下示例所示。
在 ~/.aws/config
文件中设置选项
以下示例展示了为 default
配置文件设置该选项,但您也可以将该设置添加到 ~/.aws/config
文件中的任何配置文件中。
[default]
cli_pager=
设置环境变量
Linux 或 macOS:
$
export AWS_PAGER=""
Windows:
C:\>
setx AWS_PAGER ""
AWS CLI 版本 2 现在返回 ISO 8601 格式的所有时间戳输出值。
默认情况下,AWS CLI 版本 2 返回 ISO 8601 格式
ISO 8601 格式的时间戳与以下示例类似。第一个示例通过在时间之后加入 Z
,显示以协调世界时 (UTC)T
分隔。
2019-10-31T22:21:41Z
要指定不同的时区,不是使用 Z
,而是指定 +
或 -
以及所需时区在 UTC 之前或之后的小时数作为两位数值。以下示例显示的时间与上一个示例相同,但调整为太平洋标准时间(比 UTC 晚 8 小时):
2019-10-31T14:21:41-08
要查看以由 HTTP API 响应返回的格式表示的时间戳,请将以下行添加到您的 .aws/config
配置文件中。
cli_timestamp_format = wire
AWS CLI 版本 2 改进了对 AWS CloudFormation 部署的处理,从而导致不会发生任何更改
在 AWS CLI 版本 1 中,如果您部署的 AWS CloudFormation 模板未导致任何更改,则默认情况下,AWS CLI 会失败并显示错误代码。如果您不认为这是一个错误,并希望您的脚本继续,这可能会成为一个问题。您可以通过添加返回
0
并且不会在脚本中导致错误的标记 -–no-fail-on-empty-changeset
,来解决 AWS CLI 版本 1 中的这个问题。
因为这是常见情况,所以,当部署没有导致更改,并且操作返回空更改集时,AWS CLI 版本 2 现在默认情况下返回成功退出代码 0
。
在 AWS CLI 版本 2 中,要恢复到原始行为,您必须添加新标记 --fail-on-empty-changeset
。
AWS CLI 版本 2 以更一致的方式使用 Amazon S3 密钥
对于 s3
命名空间中的 Amazon S3 自定义命令,我们改进了路径显示方式的一致性。在 AWS CLI 版本 2 中,路径始终相对于相关键显示。AWS CLI 版本 1
有时以绝对形式显示路径,有时以相对形式显示路径。
AWS CLI 版本 2 会为 us-east-1
区域使用正确的 Amazon S3 区域终端节点
将 AWS CLI 版本 1 配置为使用 us-east-1
区域时,AWS CLI 已使用全局 s3.amazonaws.com
终端节点,该终端节点以物理方式托管在该 us-east-1
区域中。在指定该区域时,AWS CLI 版本 2 现在使用真正的区域终端节点 s3.us-east-1.amazonaws.com
。要强制 AWS CLI 版本 2 使用全局终端节点,您可以将命令的区域设置为 aws-global
。
默认情况下,AWS CLI 版本 2 使用区域 AWS STS 终端节点
默认情况下,AWS CLI 版本 2 会将所有 AWS STS API 请求发送到当前配置的 AWS 区域的区域终端节点。
默认情况下,AWS CLI 版本 1 会将 AWS STS 请求发送到全局 AWS STS 终端节点。您可以使用 sts_regional_endpoints 设置来控制 V1 中的此默认行为。
AWS CLI 版本 2 将 ecr
get-login
替换为 ecr get-login-password
AWS CLI 版本 2 将 aws ecr get-login
命令替换为新的 aws
ecr get-login-password
命令,以改进与容器身份验证的自动集成。
aws ecr get-login-password
命令可降低在进程列表、shell 历史记录或其他日志文件中公开您的凭证的风险。它还提高了与 docker login
命令的兼容性,从而改善自动化处理的效果。
aws ecr get-login-password
命令在 AWS CLI 版本 1.17.10 及更高版本以及 AWS CLI 版本 2 中可用。为保持向后兼容性,较旧的 aws ecr get-login
命令仍在 AWS CLI 版本 1 中可用。
您可以使用 aws ecr get-login-password
命令来替换以下检索密码的代码。
$(aws ecr get-login -no-include-email)
要降低在 shell 历史记录或日志中公开密码的风险,请改用以下示例命令。在此示例中,密码会被直接传送给 docker login
命令,通过 --password-stdin
选项分配给密码参数。
aws ecr get-login-password | docker login --username AWS
--password-stdin
MY-REGISTRY-URL
AWS CLI 版本 2 对插件的支持会不断变化
AWS CLI 版本 2 中的插件支持只是暂时的,目的是在发布更新的稳定版插件接口之前帮助用户从 AWS CLI 版本 1 进行迁移。不保证某个特定的插件甚或是 CLI 插件接口在未来版本的 AWS CLI 版本 2 中受支持。如果您依赖于插件,请务必锁定到特定版本的 CLI,并在升级时测试插件的功能。
要启用插件支持,请在 ~/.aws/config
中创建 [plugins]
区段。
[plugins] cli_legacy_plugin_path =
<path-to-plugins>
/python3.7/site-packages<plugin-name>
=<plugin-module>
在 [plugins]
区段中,首先定义 cli_legacy_plugin_path
变量并将其值设置为插件模块所在的 Python 站点包路径。然后,您可以对插件进行配置,提供插件名称 (plugin-name
) 以及包含插件源代码的 Python 模块的文件名称 (plugin-module
)。CLI 会通过导入插件的 plugin-module
并调用插件的 awscli_initialize
函数来加载每个插件。
AWS CLI 版本 2 不再支持“隐藏”别名
AWS CLI 版本 2 不再支持版本 1 中支持的以下隐藏别名。
在下表中,第一列显示了适用于所有版本(包括 AWS CLI 版本 2)的服务、命令和参数。第二列显示不再适用于 AWS CLI 版本 2 的别名。
有效的服务、命令和参数 | 过时的别名 |
---|---|
cognito-identity create-identity-pool open-id-connect-provider-arns | open-id-connect-provider-ar-ns |
storagegateway describe-tapes tape-arns | tape-ar-ns |
storagegateway.describe-tape-archives.tape-arns | tape-ar-ns |
storagegateway.describe-vtl-devices.vtl-device-arns | vtl-device-ar-ns |
storagegateway.describe-cached-iscsi-volumes.volume-arns | volume-ar-ns |
storagegateway.describe-stored-iscsi-volumes.volume-arns | volume-ar-ns |
route53domains.view-billing.start-time | start |
deploy.create-deployment-group.ec2-tag-set | ec-2-tag-set |
deploy.list-application-revisions.s3-bucket | s-3-bucket |
deploy.list-application-revisions.s3-key-prefix | s-3-key-prefix |
deploy.update-deployment-group.ec2-tag-set | ec-2-tag-set |
iam.enable-mfa-device.authentication-code1 | authentication-code-1 |
iam.enable-mfa-device.authentication-code2 | authentication-code-2 |
iam.resync-mfa-device.authentication-code1 | authentication-code-1 |
iam.resync-mfa-device.authentication-code2 | authentication-code-2 |
importexport.get-shipping-label.street1 | street-1 |
importexport.get-shipping-label.street2 | street-2 |
importexport.get-shipping-label.street3 | street-3 |
lambda.publish-version.code-sha256 | code-sha-256 |
lightsail.import-key-pair.public-key-base64 | public-key-base-64 |
opsworks.register-volume.ec2-volume-id | ec-2-volume-id |