Alibaba Cloud CLI:レガシーのAlibaba Cloud CLIからプラグインベースCLIへの移行

比較例

DescribeRegions API を例に、プラグインベースのコマンドは次のとおりです。

aliyun ecs describe-regions --accept-language zh-CN

レガシーコマンドは次のようになります。

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

この例では、唯一の違いは命名規則です。しかし、より複雑なコマンドの場合、プラグインベースのバージョンではパラメーター名が完全に再設計されている場合があります。たとえば、一部のコマンドでは --region-id ではなく --biz-region-id が使用されます。これは、従来の --RegionId の単純な大文字/小文字の変換ではありません。移行する際は、常に <command> --help を実行するか、OpenAPI Explorer で検索して、正しいパラメーター名を確認してください。

主な違い

次のコマンドを実行して、バージョン番号を確認します。バージョンが 3.3.0 以降の場合、お使いの CLI はプラグインベースのコマンドをサポートしています。3.3.0 未満の場合は、まず CLI をアップグレードする必要があります。

aliyun version

特定のコマンドがプラグインベースかレガシーバージョンかを確認するには、aliyun <command> <sub-command> --help を実行します:

• プラグイン版：ヘルプ出力にはグローバルパラメーターセクションが含まれ、パラメーター名には通常、ケバブケーススタイル (例: --region-id) が採用されています。

• 旧バージョン: ヘルプ出力にはパラメーターセクションのみが含まれており、パラメーター名には通常、パスカルケーススタイル (例: --RegionId) が使用されます。

OpenAPI Explorerを使用した検索

レガシーコマンド名 (API アクション名) がわかっている場合、これが最も直接的なアプローチです。

1. OpenAPI Explorerを開きます。

2. 検索ボックスにレガシーコマンド名 (例: DescribeInstances) を入力すると、一致する API が検索結果に一覧表示されます。

3. 対象の API をクリックして詳細ページに移動し、必須パラメーター値を入力してから、右側の [CLI Example] タブに切り替えます。

4. プラグインベースのコマンドは [CLI Style (New)] に、レガシーコマンドは [API Native Style (Old)] に表示されます。新しいコマンドをコピーして、スクリプト内の古いコマンドを置き換えてください。

CLIホームページの参照

OpenAPI ExplorerのCLIホームページには、サポートされているすべてのプラグインベースのコマンドがクラウドサービスごとに整理されています。パラメーターの説明も記載されています。

--help でコマンドを確認する

クラウドサービス プラグインのインストール後、各レベルで --help を使用して、利用可能なコマンドとパラメーターを参照できます。たとえば、すべての ECS プラグインコマンドを表示するには：

aliyun ecs --help

特定のコマンドの使用法とパラメーターを表示するには、次のようにします。

aliyun ecs describe-instances --help

CLI Skillsを使用したクエリ

CLI Skillsにアクセスし、スキルをインストールして、エージェントを介して自然言語で要件を記述すると、対応するプラグインベースのコマンドを取得できます。

ステップ1：CLIのアップグレード

現在のバージョンを確認します。

aliyun version

バージョンが 3.3.0 より前の場合、Alibaba Cloud CLI のインストールと更新 を参照してアップグレードしてください。旧バージョンをアンインストールする必要はなく、既存の認証情報設定 (~/.aliyun/config.json) に影響はありません。

アップグレード後も、レガシーコマンドは引き続き機能し、既存のスクリプトに影響はありません。新しい機能のサポート、更新、セキュリティ修正は、プラグインベースのバージョンでのみ提供されます。

ステップ2：プラグインのインストール

必要なクラウドサービスプラグインをインストールします。

# 単一のプラグインをインストール
aliyun plugin install --name ecs

# 複数のプラグインをインストール
aliyun plugin install --names ecs oss vpc

または、環境変数を介して自動インストールを有効にすることもできます。まだインストールされていないプラグインのプラグインベースのコマンドを実行すると、CLIが自動的にダウンロードしてインストールします。

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

ステップ3：コマンドの検証

プラグインベースのコマンドを実行して、正常に機能することを確認します。

aliyun ecs describe-regions

出力にリージョンのJSONリストが表示されれば、プラグインベースのCLIが正しく機能していることが確認できます。

ステップ4：スクリプトの更新

スクリプト内のレガシーコマンドを、プラグインベースの構文に徐々に置き換えます。

1. スクリプト内のレガシーコマンドを特定してください。一般的な特徴として、2 番目の引数に PascalCase が使用されていることが挙げられます (例: aliyun ecs DescribeInstances)。

2. OpenAPI Explorerでレガシーコマンド名を検索し、対応するプラグインベースのコマンドを見つけます。

3. レガシーコマンドをプラグインベースのコマンドに置き換え、それに応じてパラメーター名を更新します。

4. 更新したスクリプトをテストします。

レガシーコマンドは新しいバージョンでも機能するため、優先度に基づいてバッチで移行できます。

CI/CDパイプライン

非インタラクティブ環境では、CLI はプラグインのインストールを促すプロンプトを表示しません。次のいずれかの方法で対処します。

• パイプラインスクリプトにプラグインをプリインストールします。

  aliyun plugin install --names ecs oss vpc

• または、環境変数を設定して自動インストールを有効にします。

  export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

すべてのビルドで有効になるように、環境変数をパイプラインのグローバル環境設定 (Jenkinsfile の environment ブロックや GitHub Actions の env セクションなど) に追加することをお勧めします。

出力解析スクリプト

プラグインベースのコマンドの JSON 出力は、従来のバージョンとは異なる場合があります。 従来の CLI は未加工の API レスポンスを返しますが、プラグインベースのバージョンは出力を処理する場合があります。 スクリプトで jq、grep、またはその他のツールを使用して CLI 出力をパースする場合、コマンドを切り替えた後に出力形式を確認してください。

複雑なコマンドの移行

複雑なパラメーターを持つコマンドは、移行中に最もエラーが発生しやすいシナリオです。

aliyun slb AddBackendServers \
  --LoadBalancerId lb-xxx \
  --BackendServers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun slb add-backend-servers \
  --load-balancer-id lb-xxx \
  --backend-servers '[{"ServerId":"i-aaa","Weight":100},{"ServerId":"i-bbb","Weight":80}]'

aliyun ecs run-instances \
  --region cn-hangzhou \
  --instance-type ecs.g7.large \
  --image-id ubuntu_22_04_x64_20G_alibase_20230China.vhd \
  --security-group-id sg-xxx \
  --vswitch-id vsw-xxx \
  --system-disk "$(cat <<'EOF'
{"Size":40,"Category":"cloud_essd","PerformanceLevel":"PL1"}
EOF
)"

aliyun ecs DescribeInstances --RegionId cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

# プラグインベースのバージョン：まず出力構造を確認してから、jq式を調整してください。
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

レガシーヘルプの表示

製品プラグインのインストール後は、aliyun <command> --help はデフォルトでプラグインのヘルプを表示します。一時的に従来のヘルプを表示するには、次の環境変数を設定します。

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

アップグレード後もレガシーのパスカルケースのコマンドを使用できますか？

はい。CLI バージョン 3.3.0 以降は下位互換性があります。ただし、最新のサポートを受けるために、最新バージョンにアップグレードすることを推奨します。

移行後に認証情報を再設定する必要がありますか？

いいえ。プラグインベースの CLI は、旧バージョンと同じ認証情報設定 (~/.aliyun/config.json) を使用します。設定済みのすべての profile エントリと環境変数による認証情報は、アップグレード後も引き続き機能します。

同じスクリプト内でレガシーコマンドとプラグインベースのコマンドを混在させることはできますか？

はい。両方のコマンド形式は同じスクリプト内に共存できます。優先度に基づいて、レガシーコマンドを徐々に置き換えることを推奨します。

プラグインのインストールに失敗した場合はどうすればよいですか？

次の順序でトラブルシューティングを行ってください。

1. お使いのネットワークが aliyuncli.alicdn.com にアクセスできるかどうかを確認してください。

2. プラグインのインストールディレクトリ (~/.aliyun/plugins/) に書き込み権限があることを確認してください。

3. aliyun version を実行して、CLI のバージョンが 3.3.0 以降であることを確認してください (以前のバージョンはプラグインをサポートしていません)。