使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版 - AWS Command Line Interface
運作方式限制設定升級偵錯模式

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版

我們建議 AWS CLI 第 1 版的使用者升級至 AWS CLI 第 2 版，以存取新功能和增強的效能。CLI AWS 第 1 版與 AWS CLI 第 2 版之間的行為有所變更，可能需要您更新指令碼或命令以取得相同的行為。當您使用 CLI AWS 第 2 版中行為不同的功能時， AWS CLI 第 1 版中的升級偵錯模式會輸出警告。此功能會自動偵測哪些 AWS CLI 第 1 版命令需要在升級至 CLI AWS 第 2 版之前修改，以防止意外問題，從而改善升級體驗。

如需詳細資訊，請參閱中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更。

當您從 AWS CLI 第 1 版升級至第 2 版時，您可能會遇到影響現有指令碼和工作流程中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更的問題。升級偵錯模式可協助您在完成遷移之前識別這些問題。

升級偵錯模式會偵測您何時使用 CLI 第 2 AWS 版中發生重大變更的功能。當您執行升級後會中斷的命令時， 模式會顯示警告，其中包含修正問題的特定步驟。這可透過自動尋找潛在問題來節省您的時間，而不是手動搜尋您的程式碼。

運作方式

如果啟用，升級偵錯模式會偵測 CLI 第 2 AWS 版中因重大變更而更新的功能使用情況。如果您在升級至 CLI AWS 第 2 版中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更後使用 中列出的命令或功能，輸出中會顯示警告。中斷變更偵測是根據使用的命令、提供的引數、執行環境 （例如環境變數、組態設定等），以及在少數情況下， AWS 使用帳戶中資源的內容或組態。

下列範例示範這些警告的外觀。此命令示範範例警告。所有警告文字都以「AWS CLI V2 UPGRADE WARNING」開頭，後面接著特定的警告訊息。在此情況下，會輸出警告，因為 命令依賴 CLI AWS 擷取 URL 的內容，並使用內容做為--template-body參數值，這是在 CLI AWS 第 2 版中移除的功能。

下列範例顯示警告的外觀：

$ aws cloudformation create-stack \
  --stack-name "stack012345" \
  --template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"

AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or 
https://, AWS CLI v2 will not automatically request the content of the URL for 
the parameter, and the `cli_follow_urlparam` option has been removed. See 
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.

下表列出所有重大變更，以及如何避免在 CLI AWS 第 2 版中面臨重大變更。解決偵錯模式中警告的修復動作為粗體。

突破性變更 在 v1 上，遷移至 v2 行為 在 v2 上，保留 v1 行為
已新增環境變數以設定文字檔案編碼 取消設定 PYTHONUTF8和 PYTHONIOENCODING環境變數。 將AWS_CLI_FILE_ENCODING環境變數設定為 v1 中指定的編碼。
預設情況下，會以 base64 編碼字串的格式傳遞二進位參數 使用 base64 編碼 參數的值。如果從檔案載入 參數，請使用 base64 編碼檔案內容。 將 cli_binary_format設定設為 raw-in-base64-out。
改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理 不適用。 無法遷移到第 1 版中的第 2 版行為。 使用 --copy-props none 參數。
不會為參數自動擷取 http:// 或 https:// URL 使用 curl （或其他工具） 將 URLs的內容下載至本機檔案。然後，使用 file：// 將檔案內容載入 參數。或者，將 cli_follow_urlparam設定為 false，將原始 URL 指定為參數值。 不適用。 無法在第 2 版中保留第 1 版行為。
預設情況下，對於所有輸出使用的分頁程式 不適用。 無法遷移到第 1 版中的第 2 版行為。 將 cli_pager設定或AWS_PAGER變數設定為空字串。
時間戳記輸出值會標準化為 ISO 8601 格式 將 cli_timestamp_format 設定設為 iso8601。 將 cli_timestamp_format設定設為有線。
改善未造成任何變更的 CloudFormation 部署處理 使用 --no-fail-on-empty-changeset 參數。 使用 --fail-on-empty-changeset 參數。
已變更 us-east-1 區域的區域性 Amazon S3 端點的預設行為 將AWS_ENDPOINT_URL_S3環境變數或--endpoint-url命令列選項設定為 us-east-1 區域 URL。 使用--region aws-global命令列選項。
已移除 ecr get-login 並替換為 ecr get-login-password (1.17.10 或更新版本） 使用 並將輸出已移除 ecr get-login 並替換為 ecr get-login-password輸送至 docker 命令。 不適用。 無法在第 2 版中保留第 1 版行為。
AWS CLI 外掛程式的第 2 版支援正在變更 不適用。 無法遷移到第 1 版中的第 2 版行為。 將 cli_legacy_plugin_path 設定為組態檔案的 [plugins]區段。測試第 2 版中的外掛程式、鎖定第 2 版，以及在每次升級時測試您的外掛程式。
已移除隱藏別名支援 從已淘汰的隱藏別名切換到已移除隱藏別名支援適用於所有版本的 。 不適用。 無法在第 2 版中保留第 1 版行為。
不支援 api_versions 組態檔案設定 將舊版 API 的用量遷移至最新的 API 版本，並從組態設定中移除 api_versions。 不適用。 無法在第 2 版中保留第 1 版行為。
AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求 指定第 4 版的簽章版本 （請參閱在請求身分驗證中指定簽章版本）。 不適用。 無法在第 2 版中保留第 1 版行為。
AWS CLI 第 2 版與分頁參數更一致 將輸入 JSON 參數中的分頁參數移至命令本身。 從輸入 JSON 參數中移除分頁參數。
AWS CLI 第 2 版在所有命令中提供更一致的傳回碼 不適用。 無法遷移到第 1 版中的第 2 版行為。 不適用。 無法在第 2 版中保留第 1 版行為。

限制

我們強烈建議客戶檢閱我們的 中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更。

不支援的中斷變更偵測

除 之外，升級偵錯模式功能支援每個重大變更AWS CLI 第 2 版在所有命令中提供更一致的傳回碼。此模式無法考慮如何使用下游 CLI AWS 傳回的錯誤代碼。

條件式中斷變更偵測

偵測時間戳記輸出值會標準化為 ISO 8601 格式是偵測取決於 AWS 帳戶狀態的唯一情況，如果稍後更新帳戶資源，則可能會發生重大變更。如果來自 服務的 API 回應中未包含時間戳記，則不會對此重大變更進行任何偵測。

如果您倚賴 CLI AWS 命令傳回的時間戳記格式，且尚未將 AWS CLI 設定為使用 ISO 8601，請採取額外的預防措施，以確保您的時間戳記處理不會在升級至第 2 版後中斷。

無法解決的中斷變更偵測

升級偵錯模式的某些警告輸出無法透過修改命令或環境來解決。下列情況下，只要您使用對應的功能，系統一律會透過升級偵錯模式輸出警告：

錯誤偵測

升級偵錯模式輸出的警告不保證升級到 AWS CLI v2 後將面臨重大變更。以下是即使 CLI v2 AWS 中沒有重大變更，仍會透過升級偵錯模式輸出警告的情況：

設定升級偵錯模式

您可以使用下列方法啟用或停用升級偵錯模式，依優先順序列出：