# アップグレードデバッグモードを使用して AWS CLI バージョン 1 を AWS CLI バージョン 2 にアップグレードする
このトピックでは、AWS CLI バージョン 1 のアップグレードデバッグモードについて説明します。
AWS CLI バージョン 1 のユーザーは、AWS CLI バージョン 2 にアップグレードして、新機能と強化されたパフォーマンスを利用することをお勧めします。このトピックでは、AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の動作の変更について説明します。この変更では、同じ動作をするために、スクリプトまたはコマンドを更新する必要があるものについて述べます。AWS CLI バージョン 1 のアップグレードデバッグモードは、AWS CLI バージョン 2 で動作が異なる機能を使用する場合に警告を出力します。この機能は、予期しない問題を防ぐために AWS CLI バージョン 2 にアップグレードする前に変更する必要がある AWS CLI バージョン 1 コマンドを自動的に検出することで、アップグレードエクスペリエンスを向上させます。
詳細については、「[AWS CLI バージョン 2 の新機能と変更点](cliv2-migration-changes.md)」の「[AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更](cliv2-migration-changes.md#cliv2-migration-changes-breaking)」を参照してください。
## 前提条件
アップグレードデバッグモード機能は、AWS CLI バージョン `1.44.0` で導入されました。
AWS CLI バージョン 1 を使用して `aws --version` を実行し、AWS CLI バージョンが `1.44.0` 以降であることを確認します。
バージョンが `1.44.0` 未満の場合は、「[AWS CLI のインストール、更新、アンインストール](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)」を参照してください。
## 仕組み
有効にすると、アップグレードデバッグモードは、AWS CLI バージョン 2 の更新で下位互換性のない変更が生じる機能が使用されている場合、それを検出します。AWS CLI バージョン 2 にアップグレードした後に [AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更](cliv2-migration-changes.md#cliv2-migration-changes-breaking) にリストされているコマンドまたは機能を使用すると、出力に警告が表示されます。互換性のない変更の検出は、使用されるコマンド、指定された引数、実行環境 (環境変数、構成設定など)、および場合によっては、使用される AWS アカウントのリソースの内容または構成に基づいています。
警告は、AWS CLI バージョン 2 へのアップグレードに伴う予期しない問題を防ぐためのアクションを示しています。警告メッセージで推奨される変更を行った後、コマンドを再実行して警告が表示されなくなったことを確認することで、コマンドが正常に更新されたことを確認できます。警告が解決されたことは、AWS CLI バージョン 2 へのアップグレード時に説明されている重大な変更が、このコマンドで発生する可能性がなくなったことを示します。
次の例は、これらの警告がどのように表示されるかを示しています。このコマンドは警告の例を示しています。すべての警告テキストは「AWS CLI V2 UPGRADE WARNING」で始まり、その後に特定の警告メッセージが続きます。この場合、コマンドは、AWS CLI で URL の内容を取得し、その内容を `--template-body` パラメータ値として使用しており、これは AWS CLI バージョン 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.
```
次の表は、すべての下位互換性のない変更と、AWS CLI バージョン 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) | URL の内容をローカルファイルにダウンロードするには、curl (または代替ツール) を使用します。次に、[file://](https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-file.html) を使用してパラメータにファイルコンテンツをロードします。または、cli\$1follow\$1urlparam を false に設定して、raw 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 設定を wire に設定します。 |
| [変更のない、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 の動作に移行できません。 | 設定ファイルの [plugins] セクションに [cli\$1legacy\$1plugin\$1path](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#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 は、署名 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 の動作を保持できません。 |
## 制限
[AWS CLI バージョン 1 と AWS CLI バージョン 2 の間の重要な変更](cliv2-migration-changes.md#cliv2-migration-changes-breaking) のレビューを強くお勧めします。
### サポートされていない互換性のない変更の検出
アップグレードデバッグモード機能は、[AWS CLI バージョン 2 は、すべてのコマンドで一貫性のあるリターンコードを提供します。](cliv2-migration-changes.md#cliv2-migration-return-codes) を除くすべての互換性のない変更をサポートします。このモードは、AWS CLI ダウンストリームから返されるエラーコードの使用方法を考慮できません。
### 条件付き互換性のない変更の検出
[タイムスタンプの出力値は ISO 8601 形式に標準化されています](cliv2-migration-changes.md#cliv2-migration-timestamp) の検出は、検出が AWS アカウントの状態に依存する唯一のケースであり、アカウントリソースが後で更新されると、下位互換性のない変更が発生する可能性があります。サービスからの API レスポンスにタイムスタンプが含まれていない場合、この互換性のない変更は検出されません。
AWS CLI コマンドによって返されるタイムスタンプ形式に依存していて、ISO 8601 を使用するように AWS CLI をまだ設定していない場合は、バージョン 2 へのアップグレード後にタイムスタンプの処理が中断されないように特に注意してください。
### 解決不可能な互換性のない変更の検出
アップグレードデバッグモードによる一部の警告出力は、コマンドまたは環境を変更しても解決できません。次のケースでは、対応する機能を使用している限り、警告がアップグレードデバッグモードで常に出力されます。
+ [AWS CLIプラグインに対する バージョン 2 のサポートが変更されます](cliv2-migration-changes.md#cliv2-migration-profile-plugins) - [設定ファイルの](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)プラグインに依存している場合、アップグレードデバッグモードは常に解決できない警告を出力します。このモードでは、いずれかのプラグインが AWS CLI バージョン 2 で動作するかどうかは保証できません。
+ [マルチパートコピーのファイルプロパティとタグの Amazon S3 処理が改善されました](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - `aws s3` を使用して bucket-to-bucket Amazon Amazon S3 コピーを実行する場合、アップグレードデバッグモードは常に解決できない警告を出力します。
### 誤検出
アップグレードデバッグモードによる警告出力は、AWS CLI V2 へのアップグレード後に必ず下位互換性のない変更があるというものではありません。以下は、AWS CLI V2 で互換性のない変更が生じていないにもかかわらず、アップグレードデバッグモードで警告が出力される場合です。
+ [テキストファイルのエンコードを設定するために環境変数を追加](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 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 設定が wire (デフォルト) に設定されており、ISO 8601 形式のタイムスタンプがサービスによって返される場合。
+ [変更のない、CloudFormation デプロイの処理の改善](cliv2-migration-changes.md#cliv2-migration-cfn) - `aws cloudformation deploy` コマンドで `--fail-on-empty-changeset` フラグが使用され、結果の変更セットが空の場合、誤検出が出力されます。また、変更セットが空ではなく、`--no-fail-on-empty-changeset` が使用されていない場合、誤検出が出力されます。
+ [`us-east-1` リージョンの Amazon S3 エンドポイントのデフォルト動作を変更しました](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) - Amazon S3 オペレーションの実行に `aws s3` または `aws s3api` が使用され、リージョンが `us-east-1` に設定されていて、`s3.us_east_1_regional_endpoint` 設定がリージョンに設定されておらず、[エンドポイント設定](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-endpoints.html#endpoints-precedence)が原因でリクエストにグローバル Amazon S3 エンドポイントが使用されている場合、デバッグモードは設定されたエンドポイント設定をチェックしないため、警告は誤検出である可能性があります。
## アップグレードデバッグモードを設定する
アップグレードデバッグモードを有効または無効にするには、次の方法を使用します。優先順位は次のとおりです。
+ コマンドラインオプションは、単一のコマンドに対してアップグレードデバッグモードを有効化または無効化します。[アップグレードデバッグモードを使用するには、--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) 変数を使用します。