Alibaba Cloud CLI:Migrar da CLI legada para a CLI baseada em plugins do Alibaba Cloud

Exemplo de comparação

Para a API DescribeRegions, o comando baseado em plugins é:

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

O comando legado é:

aliyun ecs DescribeRegions --AcceptLanguage zh-CN

Neste caso, a única alteração é a convenção de nomenclatura. No entanto, alguns comandos de plugins redesenham totalmente os parâmetros — por exemplo, --biz-region-id em vez de --region-id. Isso não é uma simples conversão de maiúsculas e minúsculas do parâmetro legado --RegionId. Sempre verifique os nomes dos parâmetros com <command> --help ou no OpenAPI Explorer.

Principais diferenças

Execute o seguinte comando para verificar sua versão. Se o resultado for 3.3.0 ou superior, sua CLI já suporta comandos baseados em plugins. Caso contrário, atualize-a primeiro.

aliyun version

Para verificar se um comando específico usa a versão baseada em plugins ou a versão legada, execute aliyun <command> <sub-command> --help:

• Versão baseada em plugins: A saída de ajuda inclui uma seção de parâmetros globais e os nomes dos parâmetros geralmente usam o estilo kebab-case (por exemplo, --region-id).

• Versão legada: A saída de ajuda inclui apenas uma seção de parâmetros e os nomes dos parâmetros geralmente usam o estilo PascalCase (por exemplo, --RegionId).

Pesquisar usando o OpenAPI Explorer

Se você souber o nome do comando legado (nome da ação da API), este é o método mais direto:

1. Abra o OpenAPI Explorer.

2. Na caixa de pesquisa, insira o nome do comando legado (por exemplo, DescribeInstances). Os resultados listarão as APIs correspondentes.

3. Clique em na API desejada para acessar sua página de detalhes, preencha os valores dos parâmetros obrigatórios e alterne para a aba CLI Example à direita.

4. O comando baseado em plugins aparece em CLI Style (New) e o comando legado em API Native Style (Old). Copie o novo comando para substituir o antigo em seu script.

Navegar pela página inicial da CLI

A página inicial da CLI no OpenAPI Explorer lista todos os comandos baseados em plugins suportados, organizados por serviço de nuvem, com descrições de parâmetros.

Descobrir comandos com --help

Após instalar um plugin de serviço de nuvem, use --help em cada nível para navegar pelos comandos e parâmetros disponíveis. Por exemplo, para visualizar todos os comandos do plugin ECS:

aliyun ecs --help

Para visualizar o uso e os parâmetros de um comando específico:

aliyun ecs describe-instances --help

Consultar usando CLI Skills

Acesse CLI Skills, instale a habilidade e descreva seus requisitos em linguagem natural por meio de um agente para obter o comando baseado em plugins correspondente.

Etapa 1: Atualizar a CLI

Verifique sua versão atual:

aliyun version

Se a versão for anterior à 3.3.0, siga as instruções em Instalar e atualizar a CLI do Alibaba Cloud para atualizar. Não é necessário desinstalar a versão legada — sua configuração de credenciais (~/.aliyun/config.json) será preservada.

Após a atualização, os comandos legados continuam funcionando. Novos recursos, suporte a produtos e correções de segurança estão disponíveis exclusivamente na versão baseada em plugins.

Etapa 2: Instalar plugins

Instale os plugins de serviços de nuvem necessários:

# Install a single plugin
aliyun plugin install --name ecs

# Install multiple plugins
aliyun plugin install --names ecs oss vpc

Alternativamente, ative a instalação automática de plugins. Ao executar um comando cujo plugin está ausente, a CLI o instala automaticamente:

export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Etapa 3: Verificar um comando

Execute um comando baseado em plugins para confirmar que tudo funciona:

aliyun ecs describe-regions

Uma lista JSON de regiões confirma que a CLI baseada em plugins está operacional.

Etapa 4: Atualizar seus scripts

Substitua gradualmente os comandos legados em seus scripts pela sintaxe baseada em plugins:

1. Identifique comandos legados em seus scripts. Um sinal comum é o segundo argumento em PascalCase (por exemplo, aliyun ecs DescribeInstances).

2. Pesquise o nome do comando legado no OpenAPI Explorer para encontrar seu equivalente baseado em plugins.

3. Substitua o comando legado pelo equivalente baseado em plugins e atualize os nomes dos parâmetros conforme necessário.

4. Teste o script atualizado.

Os comandos legados permanecem funcionais na nova versão, permitindo migrar em lotes, conforme a prioridade.

Pipelines de CI/CD

Em ambientes não interativos, a CLI não pode solicitar a instalação de plugins. Utilize uma das seguintes abordagens:

• Pré-instale os plugins no script do pipeline:

  aliyun plugin install --names ecs oss vpc

• Ou defina uma variável de ambiente para ativar a instalação automática:

  export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true

Adicione essa variável à configuração global de ambiente do pipeline (bloco environment em um Jenkinsfile ou seção env no GitHub Actions) para aplicá-la a todas as compilações.

Scripts de análise de saída

Comandos baseados em plugins podem retornar estruturas JSON diferentes dos comandos legados, que repassam as respostas brutas da API. Se seus scripts analisam a saída com jq, grep ou ferramentas similares, verifique o formato de saída após a troca.

Migração de comandos complexos

Comandos com parâmetros complexos representam a parte mais propensa a erros durante a migração.

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'

# Plugin-based version: first, check the output structure, then adjust the jq expression.
aliyun ecs describe-instances --region cn-hangzhou \
  | jq -r '.Instances.Instance[] | select(.Status=="Running") | .InstanceId'

Visualizar ajuda legada

Após instalar um plugin de produto, aliyun <command> --help exibe a ajuda do plugin por padrão. Para visualizar a ajuda legada, defina:

export ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true

Ainda posso usar comandos legados em PascalCase após a atualização?

Sim. As versões 3.3.0 e posteriores mantêm compatibilidade com versões anteriores. No entanto, apenas a versão baseada em plugins recebe novos recursos e correções.

Preciso reconfigurar as credenciais após a migração?

Não. A CLI baseada em plugins compartilha o mesmo armazenamento de credenciais (~/.aliyun/config.json). Todas as entradas de profile e credenciais de variáveis de ambiente são mantidas.

Posso misturar comandos legados e baseados em plugins no mesmo script?

Sim. Ambos os estilos coexistem no mesmo script. Substitua os comandos legados gradualmente, conforme a prioridade.

O que fazer se a instalação do plugin falhar?

Siga esta ordem para solucionar o problema:

1. Verifique se sua rede acessa aliyuncli.alicdn.com.

2. Confirme se o diretório de instalação de plugins (~/.aliyun/plugins/) tem permissões de gravação.

3. Certifique-se de que sua versão da CLI seja 3.3.0 ou superior (versões anteriores não suportam plugins). Execute aliyun version para verificar.