本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 AWS CLI v1 到 v2 遷移工具將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版 本主題說明 AWS CLI v1 到 v2 遷移工具。 我們建議 AWS CLI 第 1 版的使用者升級至 AWS CLI 第 2 版，以存取新功能和增強的效能。CLI 第 1 版與 AWS CLI 第 2 版之間的 AWS 行為有所變更，可能需要您更新指令碼或命令以取得相同的行為。 AWS CLI v1-to-v2 Migration Tool 會分析包含 AWS CLI 第 1 版命令的 bash 指令碼，並偵測 CLI 第 AWS 2 版中因重大變更而更新的功能使用情況。此外，該工具可以自動修改您的指令碼，以修正它偵測到的大多數問題。此工具透過自動偵測和修改 bash 指令碼中的 AWS CLI 第 1 版命令來改善升級體驗，以防止升級至第 2 版時發生意外問題。 相較於升級偵錯模式， AWS CLI v1 到 v2 Migration Tool 是獨立的工具，不需要執行 AWS CLI 命令。如需升級偵錯模式與 CLI v1 到 v2 遷移工具之間的完整比較， AWS 請參閱 [使用 AWS CLI 遷移工具來緩解中斷](cliv2-migration.md#using-migration-tools)中的 [第 2 AWS CLI 版的遷移指南](cliv2-migration.md)。 如需詳細資訊，請參閱 [中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中的 [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)。 ## 運作方式 AWS CLI v1 到 v2 Migration Tool 是一種 Python 套件，能夠繫結使用 AWS CLI 第 1 版的 bash 指令碼。作為靜態 linter，它不取決於 AWS 您可能已安裝在機器上的 CLI 第 1 版。透過命令列叫用 linter，其中 bash 指令碼的本機檔案路徑會以參數形式提供。 遷移工具也可以自動產生修改後的 bash 指令碼，透過修改指令碼中使用的 AWS CLI 第 1 版命令來解決其偵測到的大多數問題清單。遷移工具會修改命令，使其與第 2 AWS 版相容，並保留第 1 版的行為。 對於某些問題清單， AWS CLI v1 到 v2 遷移工具可以偵測它們，但不提供自動修正。在這些情況下，遷移工具會將它們標記為需要手動檢閱的偵測。 [限制](#migration-tool-limitations) 如需 CLI v1-to-v2 Migration Tool AWS 支援的重大變更和自動修正的完整清單，請參閱 。 ## 先決條件 ### Python 若要使用此工具，您必須安裝 Python 3.9 或更新版本。 若要驗證是否已安裝正確的 Python 版本，請在終端機中執行下列命令，並確認輸出顯示至少為 3.9 的 Python 版本。 ``` $ python3 --version ``` 如果您有較舊版本的 Python，或未安裝 Python，您可以從[官方 Python 下載頁面下載](https://www.python.org/downloads/)相容的版本。 ### pip 除了安裝相容的 Python 版本之外，您還必須`pip`已安裝 。 若要驗證 `pip` 是否已安裝，請執行下列命令： ``` $ python3 -m pip --version ``` 如果您`pip`已安裝 ，您會看到類似以下的輸出： ``` pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13) ``` 如果您尚未`pip`安裝 ，請參閱[安裝 pip](https://docs.aws.amazon.com/cli/v1/userguide/install-linux.html#install-linux-pip-pip)。 ## 安裝 在新的虛擬環境中安裝 AWS CLI v1-to-v2 遷移工具： ``` $ python3 -m venv .venv $ source .venv/bin/activate $ python3 -m pip install aws-cli-migrate ``` ## Usage ### 乾執行模式 （預設） 使用試轉模式，您可以自動偵測可能發生重大變更的 AWS CLI 第 1 版命令，而無需修改輸入指令碼： ``` $ migrate-aws-cli --script upload_s3_files.sh ``` ### 自動修正模式 使用自動修正模式時，您可以盡可能在輸入指令碼中自動偵測和更新 AWS CLI 第 1 版命令，以減輕 CLI 第 AWS 2 版中引入的變更中斷： ``` $ migrate-aws-cli --script upload_s3_files.sh --fix ``` 或者，您可以透過 `--output` 參數提供輸出路徑來撰寫更新的指令碼，而不是更新輸入指令碼： ``` $ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix ``` ### 互動式模式 透過互動式模式，您可以自動偵測可能重大變更的 AWS CLI 第 1 版命令。大多數問題清單會顯示建議的修正，以緩解 CLI AWS 第 2 版中的中斷。您可以檢閱建議的修正，並決定是否套用修正。或者，透過 `--output` 參數提供輸出路徑，以控制寫入更新指令碼的位置： ``` $ migrate-aws-cli --script upload_s3_files.sh --interactive \ --output upload_s3_files_v2.sh ``` 下列輸出程式碼片段是互動式模式中的範例調查結果： ``` 14 14│ 15 15│ aws s3 ls s3://mybucket 16 16│ 17 │-aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive 17│+aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive --copy-props none 18 18│ 19 19│ TEMPLATE_KEY="cloudformation/$(basename "$TEMPLATE_FILE")" 20 20│ examples/upload_s3_files.sh:17 [s3-copy] In AWS CLI v2, object properties will be copied from the source in multipart copies between S3 buckets. If a copy is or becomes multipart after upgrading to AWS CLI v2, extra API calls will be made. See https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-s3-copy-metadata. Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, [u] update all, [s] save and exit, [q] quit: ``` 建議的修正會以類似 Git diff 的格式顯示。遷移工具建議移除以 開頭的行`-`，並建議新增以 開頭的行`+`。在上述範例中，建議可以解譯為將 `--copy-props none` 參數新增至執行 Amazon S3 複本的 AWS CLI 第 1 版命令。 對於每個建議的修正，您可以輸入下列任何控制項： + 輸入 `y` 以接受建議的修正。 + 輸入 `n` 以拒絕目前的修正。 + 輸入 `a` 以接受具有相同類型的所有修正。 + 輸入 `r` 以拒絕具有相同類型的所有修正。 + 輸入 `u` 以接受所有剩餘的修正。 + 輸入 `s`以儲存並結束。 + 輸入 `q` 以退出而不儲存。 某些問題清單可能會標記為手動檢閱，而不建議修正。您應該檢閱這些調查結果，並驗證您是否受到所參考重大變更的影響。如果您受到這些調查結果的影響，您應該遵循調查結果描述中指定的指導進行必要的變更，以避免或準備 CLI AWS 第 2 版中引入的重大變更。 ## 限制 AWS CLI v1 至 v2 Migration Tool 目前不支援 CLI AWS 第 2 版帶來的每個重大變更，並且具有誤判案例，即使實際上不會面對重大變更，它仍會輸出命令的偵測。 我們強烈建議客戶了解 中[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)發佈的內容[第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)。 ### 文字型分析 遷移工具會在不執行指令碼的情況下分析指令碼。這限制了它如何偵測 CLI AWS 命令來中斷變更。遷移工具只能檢查 CLI AWS 命令的文字。它無法偵測在執行時間發生的問題，例如將已棄用參數儲存在變數中，而不是直接傳遞給 AWS CLI。 ### 不支援的中斷變更偵測 下表摘要說明遷移工具中中斷變更的支援範圍。 | 重大變更 | 支援偵測 | 支援自動修正 | | --- | --- | --- | | [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 否 | 否 | | [預設情況下，會以 base64 編碼字串的格式傳遞二進位參數](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 是 | 是 | | [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 是 | 是 | | [不會為參數自動擷取 `http://` 或 `https://` URL](cliv2-migration-changes.md#cliv2-migration-paramfile) | 否 | 否 | | [預設情況下，對於所有輸出使用的分頁程式](cliv2-migration-changes.md#cliv2-migration-output-pager) | 是 | 是 | | [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 否 | 否 | | [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) | 是 | 是 | | [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 否 | 否 | | [變更區域 AWS STS 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 否 | 否 | | [已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 是 | 否 | | [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 否 | 否 | | [已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases) | 是 | 是 | | [不支援 `api_versions` 組態檔案設定](cliv2-migration-changes.md#cliv2-migration-api-versions) | 否 | 否 | | [AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求](cliv2-migration-changes.md#cliv2-migration-sigv4) | 否 | 否 | | [AWS CLI 第 2 版與分頁參數更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 是 | 否 | | [AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes) | 否 | 否 |