重大變更 – 從 AWS CLI 第 1 版遷移至第 2 版

本主題描述 AWS CLI 第 1 版與 AWS CLI 第 2 版之間的行為變更，該變更可能需要您對指令碼或命令進行變更，才能在版本 2 中獲得與版本 1 中執行的相同行為。

AWS CLI 第 2 版現在使用環境變數來設定文字檔案編碼

預設情況下，文字檔案使用與安裝的語言環境相同的編碼。若要將文字檔案的編碼設定為與地區設定不同，請使用 AWS_CLI_FILE_ENCODING 環境變數。下面的例子會設定 CLI 使用視窗上的 UTF-8 來開啟文字檔案。

AWS_CLI_FILE_ENCODING=UTF-8

如需詳細資訊，請參閱 您可以使用環境變數來設定 AWS CLI。

預設情況下，AWS CLI 第 2 版現在以 base64 編碼字串的形式傳遞二進位參數

AWS CLI 第 1 版不一定能輕鬆地將二進位參數從某個命令的輸出傳遞到另一命令的輸入，而無需進行一些中繼處理。有些命令需要 base64 編碼的字串，其他命令需要 UTF8 編碼的位元組字串。AWS CLI 第 2 版讓二進位參數的處理更加一致，進而能夠更可靠地將數值從一個命令傳遞到另一個命令。

預設情況下，AWS CLI 第 2 版現在會以 base64 編碼的字串傳遞所有二進位輸入和二進位輸出參數。需要二進位輸入的參數在文件中將其類型指定為 blob (二進位大型物件)。若要以檔案形式將二進位資料傳遞至 AWS 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，以還原個別命令的設定，置換作用中的設定檔設定。

如果您使用 file:// 或 fileb:// 還原為 AWS CLI 第 1 版行為，並針對二進位參數指定檔案，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 參數來指定下列其中一個選項：

• 預設 – 預設值。指定副本包括連接至來源物件的所有標籤，以及用於非多段副本的 --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 操作，然後會使用傳回的內容作為參數的數值。因此，關聯的命令列選項 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 的數值。

AWS CLI根據預設， 第 2 版對於所有輸出使用分頁程式。

根據預設，AWS CLI 第 2 版會透過作業系統的預設分頁程式傳回所有輸出。根據預設，這個程式是在 Linux 和 macOS 上的 less 程式，以及在 Windows 上的 more程式。這可以透過一次顯示一個頁面，讓您比較容易從服務導覽大量的輸出。但是，您有時會希望所有輸出，不需要按按鍵來獲取每個頁面，例如當您正在執行指令碼時。若要執行這項操作，您可以設定 AWS CLI 第 2 版為使用不同的分頁程式或者完全不使用。若要這樣做，請設定 AWS_PAGER 環境變數或 cli_pager 檔案中的 ~/.aws/config 設定，並指定您要使用的命令。您可以指定搜尋路徑中的命令，或指定電腦上任何可用命令的完整路徑和檔案名稱。

您可以透過將變數設定為空字串 (如下列範例所示)，來完全停用所有外部分頁程式的使用。

透過在 ~/.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 格式 傳回所有時間戳記回應值。在 AWS CLI 第 1 版中，命令會以 HTTP API 回應傳回的任何格式傳回時間戳記值，但會因服務而異。

ISO 8601 格式化的時間戳記如下所示。第一個範例會以國際標準時間 (UTC) 顯示時間，方法是在時間之後併入 Z。日期和時間使用 T 分隔。

2019-10-31T22:21:41Z

若要指定不同的時區，不要指定 Z，而是指定 + 或 - 與距離所需 UTC 之前或之後的小時數 (兩位數形式)。下列範例顯示與前一個範例相同的時間，但調整為太平洋標準時間，它是 UTC 後八小時。

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 會失敗，並顯示錯誤代碼。如果您不認為這是錯誤，並希望指令碼繼續進行，則可能會出現問題。您可以在 AWS CLI 第 1 版中解決這個問題，方法是新增標記 -–no-fail-on-empty-changeset，該標記會傳回 0，卻不會在您的指令碼中造成錯誤。

因為這是常見的情況，所以在部署沒有造成任何變更，而且操作傳回空的變更集時，AWS CLI 第 2 版預設為傳回 0 的成功結束代碼。

在 AWS CLI 第 2 版中，若要還原為原始的行為，您必須新增新的標記 --fail-on-empty-changeset。

AWS CLI 第 2 版在 us-east-1 區域使用正確的 Amazon S3 區域端點

當您設定 AWS CLI 第 1 版以使用 us-east-1 區域時，AWS CLI 使用實際託管於 us-east-1 區域的全域 s3.amazonaws.com 端點。指定該區域時，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-password 取代 ecr get-login

AWS CLI 第 2 版使用新的 aws ecr get-login-password 命令取代 aws ecr get-login 命令，以改善與容器驗證的自動整合。

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 版遷移，直到發行穩定、更新的外掛程式界面。無法保證在未來版本的 AWS CLI 第 2 版中支援特定外掛程式，甚至 CLI 外掛程式界面。如果您依賴外掛程式，請務必鎖定至 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 函數來載入每個外掛程式。

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

AWS CLI 版本 2 不再支援 api_versions 組態檔案設定

AWS CLI 第 2 版不再透過使用 api_versions 組態檔案設定來支援呼叫較舊版本的 AWS 服務 API。所有 AWS CLI 命令現在會呼叫端點目前支援的最新版本服務 API。