本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 第 2 AWS CLI 版的遷移指南 本節包含將第 1 AWS CLI 版更新為第 2 AWS CLI 版的說明。 AWS CLI 第 2 版以第 1 AWS CLI 版為基礎，包含以社群意見回饋為基礎的功能和增強功能。 AWS CLI 第 2 版是 的最新主要版本， AWS CLI 並支援所有最新的功能。在第 2 版中推出的某些功能無法回溯至第 1 版，因此您必須升級才能存取這些功能。 為了避免意外問題，在您遷移至第 2 版之前，[請先了解版本之間的差異](cliv2-migration-changes.md)。第 2 AWS CLI 版包含可能需要您更新指令碼或命令才能回溯相容性的新功能和變更。 AWS CLI 第 1 版和第 2 版使用相同的`aws`命令名稱。如果您已安裝兩個版本，您的電腦會使用搜尋路徑中找到的第一個版本。這可能會導致您的`aws`命令名稱呼叫舊 AWS CLI 版本，即使您已安裝新的版本。 若要更新到第 2 AWS CLI 版，請遵循下列其中一個指示： + 如果您先前已安裝 第 1 AWS CLI 版，請遵循 中的指示[從第 1 AWS CLI 版安裝第 2 AWS CLI 版](cliv2-migration-instructions.md)。 + 如果您先前尚未安裝第 1 AWS CLI 版，請遵循 中的指示[AWS CLI入門](cli-chap-getting-started.md)。 ## 使用 AWS CLI 遷移工具來緩解中斷 CLI AWS 第 1 版與 AWS CLI 第 2 版之間的行為有所變更，可能需要您更新指令碼或命令。升級至 AWS CLI 第 2 版，而不驗證您現有的指令碼在使用 CLI 第 2 AWS 版執行指令碼時，遇到意外效果的安全遷移風險，例如對 AWS 帳戶上的資源進行意外變更。 您可以使用兩個 AWS擁有的工具來引導遷移。無論您使用哪種工具，建議您在[第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)指南[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中參考 。 ### 升級偵錯模式 升級偵錯模式是 AWS CLI 版本 1 中的一項功能，可在版本 `1.44.0` 和更高版本中使用。啟用此功能時，會檢查您執行的每個 AWS CLI AWS 命令，以判斷它在 CLI 第 2 版中是否可能有不同的行為，假設執行環境保持不變。如果執行的命令在 CLI AWS 第 2 版中會有不同的行為，則會在命令輸出旁邊顯示警告，其中包含可採取的建議動作，以在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。 使用升級偵錯模式引導遷移的主要原因是，它在偵測命令是否會面臨行為變更方面具有很高的涵蓋範圍。 中所述的 15 個重大變更中，有 14 個[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)可以使用升級偵錯模式進行偵測，如需此功能的限制[使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-upgrade-debug-mode.md)，請參閱 [限制](cli-upgrade-debug-mode.md#upgrade-mode-limitations) 中的 。另一方面，使用升級偵錯模式的主要缺點是其輸出僅與其執行環境相關；如果遷移至 AWS CLI 第 2 版後，環境中有任何 AWS CLI 組態設定變更，則仍可能發生重大變更，您應該在更新的環境中使用升級偵錯模式重新驗證。 ### AWS CLI v1 到 v2 遷移工具 AWS CLI v1 到 v2 遷移工具是一種獨立工具，可與 Python 3.9 及更高版本搭配使用。此工具是獨立於 CLI AWS 執行的靜態 linter。它會內嵌包含 CLI AWS 第 1 版命令的 bash 指令碼，這些命令在 CLI AWS 第 2 版中可能有不同的行為。對於它偵測到在 CLI AWS 第 2 版中可能具有不同行為的大多數命令，它可以自動更新指令碼中的命令，以在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。 使用 AWS CLI v1 到 v2 遷移工具來引導遷移的主要原因是它可以自動更新您的指令碼，以保留 AWS CLI 第 2 版中的 AWS CLI 第 1 版行為，節省您自行進行更新的時間和精力。另一方面，使用遷移工具的主要缺點是，它在偵測命令是否會面臨行為變更方面具有較低的涵蓋範圍。作為靜態工具，它不會檢查執行時間決定的行為變更。 ## 在升級偵錯模式和 AWS CLI v1 到 v2 遷移工具之間進行選擇 下表重點介紹升級偵錯模式與 AWS CLI v1 至 v2 遷移工具之間的主要差異，並可用來協助引導您為使用案例選擇正確的工具。 | 升級偵錯模式 | AWS CLI v1 到 v2 遷移工具 | | --- | --- | | 偵測 CLI 第 1 版與 AWS CLI 第 2 版之間 15 個重大變更中的 14 AWS 個。 | 偵測 CLI 第 1 版與 AWS AWS CLI 第 2 版之間 15 個重大變更中的 7 個。 | | 相容於可執行 CLI AWS 的任何終端機程式。 | 僅支援內嵌 bash 指令碼。 | | 需要 AWS CLI 第 1 版、版本1.44.0或更高版本。 | 獨立於 AWS CLI 執行；不需要安裝 AWS CLI。 | | 必須進行手動修正，才能在 AWS CLI 第 2 版中保留 AWS CLI 第 1 版行為。 | 自動修正大多數 CLI AWS 第 1 版命令，它在 CLI AWS 第 2 版中偵測到的行為可能不同。 | | 偵測和建議的修正僅與其執行所在的執行環境 （即 AWS CLI 組態） 相關。 | 偵測和建議的修正與環境無關。 | | 需要執行每個測試中的 AWS CLI 命令，以變更行為。 | 不需要執行任何 AWS CLI 命令。每個 bash 指令碼只需要執行一次。 | | 恰好有 5 個已知案例會輸出誤報偵測。 | 剛好有 3 個已知案例，其將輸出誤報偵測。 | 下表顯示這兩種遷移工具各[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)支援哪些 。 | 重大變更 | 透過升級偵錯模式偵測 | 由 AWS CLI v1-to-v2 遷移工具偵測 | | --- | --- | --- | | [已新增環境變數以設定文字檔案編碼](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) | 否 | 否 | ## 本區段的其他主題 + [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md) + [從第 1 AWS CLI 版安裝第 2 AWS CLI 版](cliv2-migration-instructions.md) + [使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-upgrade-debug-mode.md) + [使用 AWS CLI v1 到 v2 遷移工具將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-migration-tool.md) # 第 2 AWS CLI 版中的新功能和變更 本主題說明第 1 AWS CLI 版和第 2 AWS CLI 版之間行為的新功能和變更。這些變更可能需要您更新指令碼或命令，才能在第 2 版中獲得與在第 1 版中執行的相同行為。 **Topics** + [AWS CLI 第 2 版新功能](#cliv2-migration-changes-features) + [中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](#cliv2-migration-changes-breaking) ## AWS CLI 第 2 版新功能 AWS CLI 第 2 版是 的最新主要版本， AWS CLI 並支援所有最新的功能。由於在第 2 版中推出的某些功能無法回溯至第 1 版，因此您必須升級才能存取這些功能。重要功能如下所示： **不需要 Python 解譯器** 第 2 AWS CLI 版不需要另外安裝 Python。它包括一個嵌入式版本。 **[精靈](cli-usage-wizard.md)** 您可以搭配 第 2 AWS CLI 版使用精靈。該精靈會逐步引導您建構某些命令。 **[IAM Identity Center 驗證IAM Identity Center 概念教學課程： AWS IAM Identity Center 和 Amazon S3AWS CLI 範例](cli-configure-sso.md)** 如果您的組織使用 AWS IAM Identity Center (IAM Identity Center)，您的使用者可以登入 Active Directory、內建 IAM Identity Center 目錄，或[連線至 IAM Identity Center 的其他 IdP](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html)。然後，它們會映射到可讓您執行 AWS CLI 命令的 AWS Identity and Access Management (IAM) 角色。 **[自動提示](cli-usage-parameters-prompting.md)** 啟用時，第 2 AWS CLI 版會在您執行 命令時提示您輸入`aws`命令、參數和資源。 **[執行 的官方 Amazon ECR Public 或 Docker 映像 AWS CLI](getting-started-docker.md)** 的官方 Docker 映像 AWS CLI 提供 AWS 直接支援和維護的隔離性、可攜性和安全性。如此一來，您就可以在容器型環境中使用 第 2 AWS CLI 版，而無需自行管理安裝。 **[用戶端分頁程式](cli-usage-pagination.md#cli-usage-pagination-clientside)** 第 2 AWS CLI 版提供使用用戶端分頁程式進行輸出。根據預設，此功能會開啟並透過作業系統的預設分頁程式傳回所有輸出。 **[`aws configure import`](cli-configure-files.md#cli-config-aws_configure_import)** 匯入從 AWS 管理主控台產生的 `.csv` 憑證。系統會匯入 `.csv` 檔案，其設定檔名稱與 IAM 使用者名稱相符。 **[https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html](https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html)** 列出已配置的所有設定檔的名稱。 **[YAML 串流輸出格式](cli-usage-output-format.md#yaml-stream-output)** `yaml` 和 `yaml-stream` 格式會利用 [YAML](https://yaml.org) 格式，同時透過將資料串流傳輸給您，提供更快的大型資料集檢視回應速度。您可以先開始檢視和使用 YAML 資料，再下載整體查詢。 **[新增 DynamoDB 的高階 `ddb` 命令](https://docs.aws.amazon.com/cli/latest/reference/ddb/index.html)** 第 2 AWS CLI 版具有高階 Amazon DynamoDB 命令 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html)和 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html)。這些命令提供簡化的界面，用於將項目放入 DynamoDB 資料表，以及在 DynamoDB 資料表或索引中進行搜尋。 **[https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html](https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html)** 第 2 AWS CLI 版具有自訂`aws logs tail`命令，可追蹤 Amazon CloudWatch Logs 群組的日誌。預設情況下，該命令會傳回過去十分鐘內來自所有關聯的 CloudWatch Logs 串流的日誌。 **[為高階 `s3` 命令新增中繼資料支援](cli-services-s3-commands.md#using-s3-commands-before-large)** 第 2 AWS CLI 版會將 `--copy-props` 參數新增至高階`s3`命令。使用此參數，您可以為 Amazon Simple Storage Service (Amazon S3) 設定更多的中繼資料和標籤。 **[`AWS_REGION`](cli-configure-envvars.md#envvars-list-AWS_REGION)** 第 2 AWS CLI 版有一個 SDK AWS 相容的環境變數，稱為 `AWS_REGION`。此變數會指定 AWS 區域 要傳送請求的 。它會覆寫 `AWS_DEFAULT_REGION` 環境變數，該變數僅適用於 AWS CLI。 ## 中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更 本節說明第 1 AWS CLI 版和第 2 AWS CLI 版之間行為的所有變更。這些變更可能需要您更新指令碼或命令，才能在第 2 版中獲得與在第 1 版中執行的相同行為。 **Topics** + [已新增環境變數以設定文字檔案編碼](#cliv2-migration-encodingenvvar) + [預設情況下，會以 base64 編碼字串的格式傳遞二進位參數](#cliv2-migration-binaryparam) + [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](#cliv2-migration-s3-copy-metadata) + [不會為參數自動擷取 `http://` 或 `https://` URL](#cliv2-migration-paramfile) + [預設情況下，對於所有輸出使用的分頁程式](#cliv2-migration-output-pager) + [時間戳記輸出值會標準化為 ISO 8601 格式](#cliv2-migration-timestamp) + [改善未造成任何變更的 CloudFormation 部署處理](#cliv2-migration-cfn) + [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](#cliv2-migration-s3-regional-endpoint) + [變更區域 AWS STS 端點的預設行為](#cliv2-migration-sts-regional-endpoint) + [已移除 `ecr get-login` 並替換為 `ecr get-login-password`](#cliv2-migration-ecr-get-login) + [AWS CLI 外掛程式的第 2 版支援正在變更](#cliv2-migration-profile-plugins) + [已移除隱藏別名支援](#cliv2-migration-aliases) + [不支援 `api_versions` 組態檔案設定](#cliv2-migration-api-versions) + [AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求](#cliv2-migration-sigv4) + [AWS CLI 第 2 版與分頁參數更一致](#cliv2-migration-skeleton-paging) + [AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](#cliv2-migration-return-codes) ### 已新增環境變數以設定文字檔案編碼 預設情況下，文字檔案使用與安裝的地區設定相同的編碼。[Blob](cli-usage-parameters-types.md#parameter-type-blob)由於 AWS CLI 版本 2 使用內嵌版本的 Python，因此不支援 `PYTHONUTF8`和 `PYTHONIOENCODING`環境變數。若要將文字檔案的編碼設定為與地區設定不同，請使用 `AWS_CLI_FILE_ENCODING` 環境變數。下列範例會將 設定為 AWS CLI 在 Windows `UTF-8` 上使用 開啟文字檔案。 ``` AWS_CLI_FILE_ENCODING=UTF-8 ``` 如需詳細資訊，請參閱 [設定 的環境變數 AWS CLI](cli-configure-envvars.md)。 ### 預設情況下，會以 base64 編碼字串的格式傳遞二進位參數 在 中 AWS CLI，某些命令需要 [base64](https://wikipedia.org/wiki/Base64) 編碼的字串，而其他命令則需要 UTF-8-encoded的位元組字串。在 AWS CLI 版本 1 中，在兩種編碼字串類型之間傳遞資料通常需要一些中繼處理。第 2 AWS CLI 版讓處理二進位參數更加一致，這有助於更可靠地將值從一個命令傳遞到另一個命令。 根據預設， AWS CLI 版本 2 會將所有二進位輸入和二進位輸出參數傳遞為 base64 編碼字串 `blobs`（二進位大型物件）。如需詳細資訊，請參閱[Blob](cli-usage-parameters-types.md#parameter-type-blob)。 若要還原到第 1 AWS CLI 版行為，請使用 `cli\$1binary\$1format` 檔案組態或 `--cli-binary-format` 參數。 ### 改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理 當您使用 `aws s3` 命名空間中的 AWS CLI 版本 1 命令將檔案從一個 S3 儲存貯體位置複製到另一個儲存貯體，且該操作使用[分段複製](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CopyingObjctsMPUapi.html)時，不會將來源物件中的檔案屬性複製到目的地物件。 根據預設， AWS CLI 版本 2 中的對應命令會將所有標籤和部分屬性從來源傳輸到目的地複本。相較於第 1 AWS CLI 版，這可能會導致對 Amazon S3 端點進行更多的 AWS API 呼叫。若要變更 AWS CLI 版本 2 中`s3`命令的預設行為，請使用 `--copy-props` 參數。 如需詳細資訊，請參閱[分段副本中的檔案屬性和標籤](cli-services-s3-commands.md#using-s3-commands-before-tags)。 ### 不會為參數自動擷取 `http://` 或 `https://` URL 當參數值以 `http://`或 開頭時，第 2 AWS CLI 版不會執行`GET`操作`https://`，也不會使用傳回的內容做為參數值。因此，相關聯的命令列選項`cli_follow_urlparam`會從第 2 AWS CLI 版中移除。 如果您需要擷取 URL 並將該 URL 內容傳遞至參數值，我們建議您使用 `curl` 或類似的工具，將 URL 的內容下載至本機檔案。然後使用 `file://` 語法讀取該檔案的內容，並將其作為參數值使用。 例如，下列命令不再會嘗試擷取在 `http://www.example.com` 找到的頁面內容，並傳遞這些內容作為參數。而是會傳遞文字字串 `https://example.com` 作為參數。 ``` $ aws ssm put-parameter \ --value http://www.example.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` 的數值。 ### 預設情況下，對於所有輸出使用的分頁程式 根據預設，第 2 AWS CLI 版會透過作業系統的預設分頁程式傳回所有輸出。此程式是在 Linux 和 macOS 上的 [https://ss64.com/bash/less.html](https://ss64.com/bash/less.html) 程式，以及在 Windows 上的 [https://docs.microsoft.com/windows-server/administration/windows-commands/more](https://docs.microsoft.com/windows-server/administration/windows-commands/more) 程式。這可以透過一次顯示一個輸出頁面，讓您比較容易瀏覽來自服務的大量輸出。 您可以設定第 2 AWS CLI 版使用不同的分頁程式，或完全不使用。如需詳細資訊，請參閱[用戶端分頁程式](cli-usage-pagination.md#cli-usage-pagination-clientside)。 ### 時間戳記輸出值會標準化為 ISO 8601 格式 根據預設，第 2 AWS CLI 版會以 [ISO 8601 格式](https://wikipedia.org/wiki/ISO_8601)傳回所有時間戳記回應值。在第 1 AWS CLI 版中，命令會以 HTTP API 回應傳回的任何格式傳回時間戳記值，這可能因服務而異。 若要以 HTTP API 回應傳回的格式查看時間戳記，請使用您的 `config` 檔案中的 `wire` 值。如需詳細資訊，請參閱 `cli\$1timestamp\$1format`。 ### 改善未造成任何變更的 CloudFormation 部署處理 根據預設，在第 1 AWS CLI 版中，如果您部署的 CloudFormation 範本不會造成任何變更，則 會 AWS CLI 傳回失敗的錯誤碼。如果您不認為這是錯誤，並希望指令碼繼續進行，將會發生問題。您可以透過新增 旗標 來解決第 1 AWS CLI 版中的問題`-–no-fail-on-empty-changeset`，該旗標會傳回 `0`。 由於這是常見的使用案例，因此當部署未造成任何變更，且操作傳回空的變更集`0`時，第 2 AWS CLI 版預設會傳回 的成功結束碼。 若要還原為原始的行為，請新增旗標 `--fail-on-empty-changeset`。 ### 已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為 當您將AWS CLI 版本 1 設定為使用 `us-east-1`區域時， AWS CLI 會使用實際託管在 `us-east-1`區域中的全域`s3.amazonaws.com`端點。指定區域`s3.us-east-1.amazonaws.com`時，第 2 AWS CLI 版會使用真正的區域端點。若要強制 AWS CLI 版本 2 使用全域端點，您可以將命令的區域設定為 `aws-global`。 ### 變更區域 AWS STS 端點的預設行為 根據預設， AWS CLI 版本 2 會將 all AWS Security Token Service (AWS STS) API 請求傳送至目前設定的 區域端點 AWS 區域。 根據預設， `1.42.0` 第 1 AWS CLI 版的任何 版本都會將請求傳送至 AWS STS 全域 AWS STS 端點。您可以藉由使用 [https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints) 設定，在第 1 版中控制此預設行為。 如果您從這些較新版本遷移到第 2 AWS CLI 版，則 或之後的任何版本`1.42.0`都會使用區域端點做為預設值，此行為保持不變。 ### 已移除 `ecr get-login` 並替換為 `ecr get-login-password` 第 2 AWS CLI 版會將 命令取代`aws ecr get-login`為 `aws ecr get-login-password`命令，以改善與容器身分驗證的自動化整合。 `aws ecr get-login-password` 命令可降低在程式清單、Shell 歷史記錄或其他日誌檔中公開憑證的風險。它也改善了與 `docker login` 命令的相容性，以獲得更好的自動化。 此`aws ecr get-login-password`命令適用於 1.17.10 AWS CLI 版和更新版本，以及 第 2 AWS CLI 版。舊版 `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 版參考指南*中的 [https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html)。 ### AWS CLI 外掛程式的第 2 版支援正在變更 第 2 AWS CLI 版中的外掛程式支援完全是暫時性的，旨在協助使用者從第 1 AWS CLI 版遷移，直到發行穩定且更新的外掛程式界面為止。不保證未來版本 AWS CLI 2 將支援特定外掛程式，甚至 AWS CLI 外掛程式界面。如果您依賴外掛程式，請務必鎖定 的特定版本， AWS CLI 並在升級時測試外掛程式的功能。 若要啟用外掛程式支援，請在 `~/.aws/config` 中建立 `[plugins]` 區段。 ``` [plugins] cli_legacy_plugin_path = /python3.7/site-packages = ``` 在 `[plugins]` 區段中，定義 `cli_legacy_plugin_path` 變數並將其值設定為您的外掛程式模組所在的 Python 站台套件路徑。然後，您可以透過提供外掛程式的名稱 (`plugin-name`) 和 Python 模組的檔案名稱 (`plugin-module`)，其中包含您的外掛程式的原始程式碼來設定外掛程式。會透過匯入 `plugin-module`並呼叫其 `awscli_initialize`函數來 AWS CLI 載入每個外掛程式。 ### 已移除隱藏別名支援 AWS CLI 第 2 版不再支援第 1 版中支援的下列隱藏別名。 在下表中，第一欄顯示可在所有版本中運作的服務、命令和參數，包括第 2 AWS CLI 版。第二欄顯示不再適用於第 2 AWS CLI 版的別名。 | 運作的服務、命令和參數 | 過時的別名 | | --- | --- | | 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 | ### 不支援 `api_versions` 組態檔案設定 AWS CLI 第 2 版不支援使用`api_versions`組態檔案設定呼叫較早版本的 AWS 服務 APIs。所有 AWS CLI 命令現在都會呼叫端點目前支援之服務 APIs 的最新版本。 ### AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求 第 2 AWS CLI 版不支援舊版簽章演算法，以密碼編譯方式驗證傳送至 Amazon S3 端點的服務請求。此簽署會在每個 Amazon S3 請求中自動執行，並且僅支援 [Signature Version 4 簽署程序](https://docs.aws.amazon.com/AmazonS3/latest/userguide/reference_aws-signing.html)。您無法設定簽章版本。所有 Amazon S3 儲存貯體預先簽章的 URL 現在僅使用 Sigv4，最長有效期為一週。 ### AWS CLI 第 2 版與分頁參數更一致 在 AWS CLI 版本 1 中，如果您在命令列指定分頁參數，則自動分頁會如預期關閉。但是，當您使用具有 `‐‐cli-input-json` 參數的檔案指定分頁參數，而自動分頁未關閉時，可能會導致非預期的輸出。無論您如何提供參數，第 2 AWS CLI 版都會關閉自動分頁。 ### AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼 AWS CLI 與版本 AWS CLI 1 相比，版本 2 在所有命令中更為一致，並正確傳回適當的結束程式碼。我們也新增了結束代碼 252、253 和 254。如需結束代碼的詳細資訊，請參閱 [AWS CLI 中的命令列傳回碼](cli-usage-returncodes.md)。 如果您依賴 AWS CLI 版本 1 如何使用傳回碼值，建議您檢查結束碼，以確保您取得預期的值。 # 從第 1 AWS CLI 版安裝第 2 AWS CLI 版 本主題提供從第 1 AWS CLI 版遷移到第 2 AWS CLI 版的說明。 AWS CLI 第 1 版和第 2 版使用相同的`aws`命令名稱。如果您已安裝兩個版本，您的電腦會使用搜尋路徑中找到的第一個版本。如果您先前已安裝第 1 AWS CLI 版，建議您執行下列其中一項操作，以使用第 2 AWS CLI 版： + ** 建議** – [解除安裝第 1 AWS CLI 版，並僅使用第 2 AWS CLI 版](#cliv2-migration-instructions-migrate)。 + [若要同時安裝兩個版本](#cliv2-migration-instructions-side-by-side)，請使用作業系統的功能，為兩個 `aws` 命令之一建立具有不同名稱的符號連結 (symlink) 或別名。 如需第 1 版和第 2 版之間重大變更的詳細資訊，請參閱 [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)。 ## 將版本 1 替換為版本 2 執行下列步驟，將 AWS CLI 第 1 版取代為第 2 AWS CLI 版。 **將 AWS CLI 第 1 版取代為第 2 AWS CLI 版** 1. 透過確認 [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md) 第 1 版和第 2 版之間的重大變更，為您現有的所有指令碼做好遷移的準備。您可以使用升級偵錯模式功能，依照 中的指示來引導您的準備[使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版](cli-upgrade-debug-mode.md)。 1. 在安裝、更新和解除安裝第 1 AWS CLI 版中，遵循作業系統的解除安裝說明來解除安裝第 1 版。 [AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html) 1. 使用以下命令確認 AWS CLI 已完全解除安裝 。 ``` $ aws --version ``` 根據輸出完成下列其中一項操作： + **未傳回版本：**您已成功解除安裝第 1 AWS CLI 版，可以繼續進行下一個步驟。 + **傳回版本：**您仍然安裝 第 1 AWS CLI 版。如需疑難排解步驟，請參閱[解除安裝 後，「`aws --version`」命令會傳回版本 AWS CLI](cli-chap-troubleshooting.md#tshoot-uninstall-1)。執行故障診斷步驟，直到未接收到版本輸出。 1. 遵循 中適用於您作業系統的適當安裝說明來安裝第 2 AWS CLI 版[安裝或更新至最新版本的 AWS CLI](getting-started-install.md)。 ## 並排安裝 若要同時安裝兩個版本，請使用作業系統的功能，為兩個 `aws` 命令之一建立具有不同名稱的符號連結 (symlink) 或別名。 1. 遵循 中適用於您作業系統的適當安裝說明來安裝第 2 AWS CLI 版[安裝或更新至最新版本的 AWS CLI](getting-started-install.md)。 1. 使用您作業系統的功能，為兩個`aws`命令之一建立不同名稱的符號連結或別名，例如*`aws2`*針對第 2 AWS CLI 版使用 。以下是第 2 AWS CLI 版的符號連結範例。以您的安裝位置替換 *PATH*。 ------ #### [ Linux and macOS ] 您可以在 Linux 和 macOS 上si y使用[符號連結](https://www.linux.com/topic/desktop/understanding-linux-links/)或[別名](https://www.linux.com/topic/desktop/aliases-diy-shell-commands/)。 ``` $ alias aws2='PATH' ``` ------ #### [ Windows command prompt ] 在 Windows 上使用 [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey)。 ``` C:\> doskey aws2=PATH ``` ------ # 使用升級偵錯模式將 AWS CLI 第 1 版升級至 AWS CLI 第 2 版 本主題說明 CLI 第 AWS 1 版中的升級偵錯模式。 我們建議 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 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)中的 [第 2 AWS CLI 版中的新功能和變更](cliv2-migration-changes.md)。 ## 先決條件 升級偵錯模式功能已引入版本 中的 AWS CLI`1.44.0`。 使用 AWS CLI 第 1 版，執行 `aws --version`，並確認 CLI AWS 版本為 `1.44.0` 或更新版本。 如果版本小於 `1.44.0`，請參閱[安裝、更新和解除安裝 AWS CLI](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)。 ## 運作方式 如果啟用，升級偵錯模式會偵測 CLI 第 2 AWS 版中因重大變更而更新的功能使用情況。如果您在升級至 CLI AWS 第 2 版[中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)後使用 中列出的命令或功能，輸出中會顯示警告。中斷變更偵測是根據使用的命令、提供的引數、執行環境 （例如環境變數、組態設定等），以及在少數情況下， AWS 使用帳戶中資源的內容或組態。 警告說明動作，以防止升級至 CLI AWS 第 2 版時發生非預期的問題。進行警告訊息建議的變更後，您可以重新執行命令以確認警告不再顯示，以確認命令已成功更新。正在解決的警告表示命令不會再遇到升級到 CLI AWS 第 2 版時所描述的重大變更。 下列範例示範這些警告的外觀。此命令示範範例警告。所有警告文字都以「AWS CLI V2 UPGRADE WARNING」開頭，後面接著特定的警告訊息。在此情況下，會輸出警告，因為 命令依賴 AWS CLI 擷取 URL 的內容，並使用內容做為`--template-body`參數值，這是在 CLI 第 2 版中移除 AWS 的功能。 ``` $ 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 行為 | | --- | --- | --- | | [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 取消設定 PYTHONUTF8和 PYTHONIOENCODING 環境變數。 | 將AWS\$1CLI\$1FILE\$1ENCODING環境變數設定為 v1 中指定的編碼。 | | [預設情況下，會以 base64 編碼字串的格式傳遞二進位參數](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 使用 base64 編碼 參數的值。如果從檔案載入 參數，請使用 base64 編碼檔案內容。 | 將 cli\$1binary\$1format設定設為 raw-in-base64-out。 | | [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 使用 --copy-props none 參數。 | | [不會為參數自動擷取 `http://` 或 `https://` URL](cliv2-migration-changes.md#cliv2-migration-paramfile) | 使用 curl （或其他工具） 將 URLs的內容下載到本機檔案。然後，使用 file[：//](https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-file.html) 將檔案內容載入 參數。或者，將 cli\$1follow\$1urlparam設定為 false，將原始 URL 指定為參數值。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | | [預設情況下，對於所有輸出使用的分頁程式](cliv2-migration-changes.md#cliv2-migration-output-pager) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 將cli\$1pager設定或AWS\$1PAGER變數設定為空字串。 | | [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) | 將 cli\$1timestamp\$1format 設定設為 iso8601。 | 將 cli\$1timestamp\$1format設定設為有線。 | | [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) | 使用 --no-fail-on-empty-changeset 參數。 | 使用 --fail-on-empty-changeset 參數。 | | [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 將AWS\$1ENDPOINT\$1URL\$1S3環境變數或--endpoint-url命令列選項設定為 us-east-1 [區域 URL](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。 | 使用--region aws-global命令列選項。 | | [已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | (1.17.10 或更新版本） 使用 並將輸出[已移除 `ecr get-login` 並替換為 `ecr get-login-password`](cliv2-migration-changes.md#cliv2-migration-ecr-get-login)輸送到 docker 命令。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | | [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 將 [cli\$1legacy\$1plugin\$1path](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#plugins) 設定為組態檔案的 [plugins]區段。測試第 2 版中的外掛程式、鎖定第 2 版，以及在每次升級時測試您的外掛程式。 | | [已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases) | 從已淘汰的隱藏別名切換到[已移除隱藏別名支援](cliv2-migration-changes.md#cliv2-migration-aliases)適用於所有版本的 。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | | [不支援 `api_versions` 組態檔案設定](cliv2-migration-changes.md#cliv2-migration-api-versions) | 將舊版 API 的用量遷移至最新的 API 版本，並從組態設定中移除 [api\$1versions](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-api_versions)。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | | [AWS CLI 第 2 版僅使用 Signature v4 來驗證 Amazon S3 請求](cliv2-migration-changes.md#cliv2-migration-sigv4) | 指定第 4 版的簽章版本 （請參閱[在請求身分驗證中指定簽章版本）](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html)。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | | [AWS CLI 第 2 版與分頁參數更一致](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 將輸入 JSON 參數中的分頁參數移至命令本身。 | 從輸入 JSON 參數中移除分頁參數。 | | [AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes) | 不適用。 無法遷移到第 1 版中的第 2 版行為。 | 不適用。 無法在第 2 版中保留第 1 版行為。 | ## 限制 我們強烈建議客戶檢閱我們的 [中斷第 1 AWS CLI 版和第 2 AWS CLI 版之間的變更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)。 ### 不支援的中斷變更偵測 升級偵錯模式功能支援每個重大變更，但 除外[AWS CLI 第 2 版在所有命令中提供更一致的傳回代碼](cliv2-migration-changes.md#cliv2-migration-return-codes)。此模式無法考慮如何使用下游 CLI AWS 傳回的錯誤代碼。 ### 條件式中斷變更偵測 偵測 [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) 是偵測取決於 AWS 帳戶狀態的唯一情況，如果稍後更新帳戶資源，則可能會有重大變更。如果來自 服務的 API 回應中未包含時間戳記，則不會對此重大變更進行任何偵測。 如果您依賴 CLI AWS 命令傳回的時間戳記格式，且尚未將 AWS CLI 設定為使用 ISO 8601，請採取額外的預防措施，以確保您的時間戳記處理不會在升級至第 2 版後中斷。 ### 無法解決的中斷變更偵測 升級偵錯模式的某些警告輸出無法透過修改命令或環境來解決。下列情況下，只要您使用對應的功能，系統一律會透過升級偵錯模式輸出警告： + [AWS CLI 外掛程式的第 2 版支援正在變更](cliv2-migration-changes.md#cliv2-migration-profile-plugins) - 如果您倚賴[組態檔案中](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)的外掛程式，升級偵錯模式一律會輸出無法解析的警告。此模式無法保證您的任何外掛程式是否可在 CLI AWS 第 2 版中運作。 + [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - 如果 `aws s3` 用來執行bucket-to-bucket Amazon S3 複製，則升級偵錯模式一律會輸出無法解決的警告。 ### 錯誤偵測 升級偵錯模式的警告輸出不保證升級到 AWS CLI v2 後將面臨重大變更。以下是即使 CLI v2 AWS 中沒有重大變更，仍會透過升級偵錯模式輸出警告的情況： + [已新增環境變數以設定文字檔案編碼](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) - 如果指定 `PYTHONUTF8`或 `PYTHONIOENCODING`環境變數來設定文字檔案編碼，且指定的編碼已符合安裝的區域設定，則警告可能是錯誤偵測，因為偵錯模式不會檢查編碼是否符合安裝的區域設定。 + [改善 Amazon S3 針對分段副本的檔案屬性和標籤的處理](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - 如果 `aws s3` 用來執行bucket-to-bucket體 Amazon S3 複製，而且由於來源物件低於分段[閾值大小](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#multipart-threshold)，則不會輸出假偵測。 + [時間戳記輸出值會標準化為 ISO 8601 格式](cliv2-migration-changes.md#cliv2-migration-timestamp) - 如果 cli\$1timestamp\$1format 組態設定為有線 （預設），服務會傳回 ISO 8601 格式的時間戳記。 + [改善未造成任何變更的 CloudFormation 部署處理](cliv2-migration-changes.md#cliv2-migration-cfn) - 如果 `--fail-on-empty-changeset`旗標與 `aws cloudformation deploy`命令搭配使用，且產生的變更集為空，則會輸出 false 偵測。此外，如果變更集不是空`--no-fail-on-empty-changeset`的，而且未使用，則會輸出 false 偵測。 + [已變更 `us-east-1` 區域的區域性 Amazon S3 端點的預設行為](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) - 如果 `aws s3`或 `aws s3api` 用於執行 Amazon S3 操作，且區域設定為 `us-east-1`，且`s3.us_east_1_regional_endpoint`組態未設定為區域性，且全域 Amazon S3 端點因[端點組態設定](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-endpoints.html#endpoints-precedence)而用於請求，則警告可能是錯誤偵測，因為偵錯模式不會檢查設定的端點設定。 ## 設定升級偵錯模式 您可以使用下列方法啟用或停用升級偵錯模式，依優先順序列出： + 命令列選項會啟用或停用單一命令的升級偵錯模式。使用 [--v2-debug](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-options.html#cli-configure-options-v2-debug) 來使用升級偵錯模式。 + 環境變數使用 [AWS\$1CLI\$1UPGRADE\$1DEBUG\$1MODE](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-envvars.html#envvars-list-aws_cli_upgrade_debug_mode) 變數。 # 使用 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) | 否 | 否 |