重大变更 – 从 Amazon CLI 版本 1 迁移到版本 2 - Amazon Command Line Interface
文件编码环境变量传递二进制参数改进了 s3 copy 操作期间的 Amazon S3 属性和标签处理不自动检索网页以获取参数输出分页所有日期/时间值均为 ISO 8601 格式改进了对 Amazon CloudFormation 部署的处理Amazon S3 和 us-east-1 区域Amazon STS 和区域终端节点弃用 ecr get-login对 [plugins] 的支持会不断变化没有隐藏的别名不再支持 api_versions
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

重大变更 – 从 Amazon CLI 版本 1 迁移到版本 2

本主题介绍 Amazon CLI 版本 1 和 Amazon CLI 版本 2 之间行为的变化，这些变化可能要求您对脚本或命令进行更改，以便在版本 2 中获得与版本 1 中相同的行为。

Amazon CLI 版本 2 现在使用环境变量设置文本文件编码

默认情况下，文本文件使用与已安装的区域设置相同的编码。要将文本文件的编码设置为不同于区域设置，请使用 AWS_CLI_FILE_ENCODING 环境变量。下面的示例将 CLI 设置为在 Windows 上使用 UTF-8 打开文本文件。

AWS_CLI_FILE_ENCODING=UTF-8

有关更多信息，请参阅用于配置 Amazon CLI 的环境变量。

预设情况下，Amazon CLI 版本 2 现在将二进制参数作为 base64 编码字符串进行传递

Amazon CLI 版本 1 并不总是能够在不需要一些中间处理的情况下，很轻松地将二进制参数从一个命令的输出传递到另一个命令的输入。有些命令需要 base64 编码字符串，其他命令需要 UTF8 编码字节字符串。Amazon CLI 版本 2 使得处理二进制参数更加一致，从而能够更可靠地将值从一个命令传递到另一个命令。

预设情况下，Amazon CLI 版本 2 现在将所有二进制输入和二进制输出参数作为 base64 编码字符串进行传递。需要二进制输入的参数在文档中将其类型指定为 blob（二进制大型对象）。要将二进制数据作为文件传递给 Amazon CLI 参数，您可以通过 Amazon CLI 版本 2 指定使用以下前缀的文件：

  • file:// – Amazon CLI 会将文件内容作为 base64 编码文本进行处理。例如：--some-param file://~/my/path/file-with-base64.txt

  • fileb:// – Amazon CLI 会将文件内容作为未编码的二进制文件进行处理。例如：--some-param fileb://~/my/path/file-with-raw-binary.bin

您可以通过在 ~/.aws/config 文件中为配置文件指定以下行来告诉 Amazon CLI 版本 2 恢复到 Amazon CLI 版本 1 行为。

cli_binary_format=raw-in-base64-out

您还可以通过在命令行中包含参数 --cli-binary-format raw-in-base64-out 来恢复单个命令的设置，覆盖活动配置文件设置。

如果您恢复为 Amazon CLI 版本 1 行为，并使用 file:// 或 fileb:// 指定二进制参数文件，Amazon CLI 会将文件内容作为未编码的原始二进制文件来处理。

Amazon CLI 版本 2 改进了执行分段复制时对文件属性和标签的 Amazon S3 处理

当您使用 aws s3 命名空间中的 Amazon CLI 版本 1 版本命令将文件从一个 Amazon S3 存储桶位置复制到另一个 Amazon S3 存储桶位置，并且该操作使用分段复制时，源对象中的文件属性不会被复制到目标对象。

现在，在预设情况下，s3 命名空间中执行分段复制的 Amazon CLI 版本 2 命令会将所有标签和以下属性集从源副本传输到目标副本：content-type、content-language、content-encoding、content-disposition、cache-control、expires 和 metadata。

这可能会导致对 Amazon S3 终端节点进行其他 Amazon API 调用，而在使用 Amazon CLI 版本 1 时，将不会进行这些调用。这些调用可能包括：HeadObject、GetObjectTagging 和 PutObjectTagging。

如果需要在 Amazon CLI 版本 2 命令中更改此默认行为，请使用 --copy-props 参数指定以下选项之一：

  • default – 默认值。指定该复制包含附加到源对象的所有标签以及用于非分段复制的 --metadata-directive 参数所包含的属性：content-type、content-language、content-encoding、content-disposition、cache-control、expires 和 metadata。

  • metadata-directive – 指定该复制仅包含用于非分段复制的 --metadata-directive 参数所包含的属性。它不会复制任何标签。

  • none – 指定该复制不包含源对象中的任何属性。

Amazon CLI 版本 2 不再自动检索 http:// 或 https:// URL 以获取参数

当参数值以 http:// 或 https:// 开头，然后使用返回的内容作为参数的值时，Amazon CLI 版本 2 不再执行 GET 操作。因此，将删除关联的命令行选项 cli_follow_urlparam。

如果您需要检索 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 的值传递。

预设情况下，Amazon CLI 版本 2 会对所有输出使用分页程序。

预设情况下，Amazon CLI 版本 2 会通过操作系统的原定设置分页程序返回所有输出。默认情况下，此程序是 Linux 和 macOS 上的 less 程序，以及 Windows 上的 more 程序。通过分页，系统可以一次一页地显示服务输出，从而让您能够更轻松地浏览大量输出。但是，您有时不想通过按键的方式来逐页获取输出，而想要一次性获得所有输出，例如当您运行脚本时。这时，您可以将 Amazon CLI 版本 2 配置为使用其他分页程序或不使用分页程序。为实现此目的，您可以在 ~/.aws/config 文件中配置 AWS_PAGER 环境变量或 cli_pager 设置，并指定要使用的命令。您可以指定搜索路径中的命令，或者指定电脑上可用的任何命令的完整路径和文件名。

要完全禁用外部分页程序，您可以将该变量设置为空字符串，如以下示例所示。

在 ~/.aws/config 文件中设置选项

以下示例展示了为 default 配置文件设置该选项，但您也可以将该设置添加到 ~/.aws/config 文件中的任何配置文件中。

[default]
cli_pager=

设置环境变量

Linux 或 macOS：

$ export AWS_PAGER=""

Windows:

C:\> setx AWS_PAGER ""

Amazon CLI 版本 2 现在返回 ISO 8601 格式的所有时间戳输出值

预设情况下，Amazon CLI 版本 2 返回 ISO 8601 格式的所有时间戳响应值。在 Amazon CLI 版本 1 中，命令以 HTTP API 响应返回的任何格式返回时间戳值，而格式可能因服务而异。

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

Amazon CLI 版本 2 改进了对 Amazon CloudFormation 部署的处理，从而导致不会发生任何更改

在 Amazon CLI 版本 1 中，如果您部署的 Amazon CloudFormation 模板未导致任何更改，则预设情况下，Amazon CLI 会失败并显示错误代码。如果您不认为这是一个错误，并希望您的脚本继续，这可能会成为一个问题。您可以通过添加返回 0 并且不会在脚本中导致错误的标记 -–no-fail-on-empty-changeset，来解决 Amazon CLI 版本 1 中的这个问题。

因为这是常见情况，所以，当部署没有导致更改，并且操作返回空更改集时，Amazon CLI 版本 2 现在默认情况下返回成功退出代码 0。

在 Amazon CLI 版本 2 中，要恢复到原始行为，您必须添加新标记 --fail-on-empty-changeset。

Amazon CLI 版本 2 为 us-east-1 区域使用正确的 Amazon S3 区域终端节点

将 Amazon CLI 版本 1 配置为使用 us-east-1 区域时，Amazon CLI 已使用全局 s3.amazonaws.com 终端节点，该终端节点以物理方式托管在该 us-east-1 区域中。在指定该区域时，Amazon CLI 版本 2 现在使用真正的区域终端节点 s3.us-east-1.amazonaws.com。要强制 Amazon CLI 版本 2 使用全局终端节点，您可以将命令的区域设置为 aws-global。

预设情况下，Amazon CLI 版本 2 使用区域 Amazon STS 终端节点

预设情况下，Amazon CLI 版本 2 会将所有 Amazon STS API 请求发送到当前配置的 Amazon 区域的区域终端节点。

预设情况下，Amazon CLI 版本 1 将 Amazon STS 请求发送到全局 Amazon STS 终端节点。您可以使用 sts_regional_endpoints 设置来控制 V1 中的此默认行为。

Amazon CLI 版本 2 将 ecr get-login 替换为 ecr get-login-password

Amazon CLI 版本 2 将 aws ecr get-login 命令替换为新的 aws ecr get-login-password 命令，以改进与容器身份验证的自动集成。

aws ecr get-login-password 命令可降低在进程列表、shell 历史记录或其他日志文件中公开您的凭证的风险。它还提高了与 docker login 命令的兼容性，从而改善自动化处理的效果。

该 aws ecr get-login-password 命令在 Amazon CLI 版本 1.17.10 及更高版本以及 Amazon CLI 版本 2 中提供。为保持向后兼容性，较旧的 aws ecr get-login 命令仍在 Amazon 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

Amazon CLI 版本 2 对插件的支持会不断变化

Amazon CLI 版本 2 中的插件支持只是暂时的，目的是在发布更新的稳定版插件接口之前帮助用户从 Amazon CLI 版本 1 进行迁移。不保证某个特定的插件甚或是 CLI 插件接口在未来版本的 Amazon CLI 版本 2 中受支持。如果您依赖于插件，请务必锁定到特定版本的 CLI，并在升级时测试插件的功能。

要启用插件支持，请在 [plugins] 中创建 ~/.aws/config 区段。

[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 函数来加载每个插件。

Amazon CLI 版本 2 不再支持“隐藏”别名

Amazon CLI 版本 2 不再支持版本 1 中支持的以下隐藏别名。

在下表中，第一列显示了适用于所有版本（包括 Amazon CLI 版本 2）的服务、命令和参数。第二列显示不再适用于 Amazon 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

Amazon CLI 版本 2 不再支持 api_versions 配置文件设置

Amazon CLI 版本 2 不再支持使用 api_versions 配置文件设置调用旧版本的 Amazon 服务 API。所有 Amazon CLI 命令现在可调用终端节点当前支持的服务 API 的最新版本。