重大變更 – 從 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 版在 us-east-1 區域使用正確的 Amazon S3 區域端點
- 預設情況下,AWS CLI 第 2 版使用區域的 AWS STS 端點
- AWS CLI 第 2 版已用 ecr get-login-password 取代 ecr get-login
- AWS CLI對外掛程式的 第 2 版支援正在改變
- AWS CLI 第 2 版不再支援「隱藏」別名
- AWS CLI 版本 2 不再支援 api_versions 組態檔案設定
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
預設情況下,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
more
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 格式
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。