Instale e gerencie plugins do Alibaba Cloud CLI | serialização de parâmetros - Alibaba Cloud CLI: Central de Documentação do Alibaba Cloud

Pré-requisitos

Instale o Alibaba Cloud CLI versão 3.3.0 ou posterior. Para instruções de instalação, consulte Instalar, atualizar e desinstalar o Alibaba Cloud CLI.
Configure as credenciais do Alibaba Cloud CLI. Para obter instruções, consulte Configurar e gerenciar credenciais.

Início rápido

Este exemplo instala o plugin ecs e consulta regiões:

# Install a plugin (using the ecs plugin as an example)
aliyun plugin install --name ecs

# Call an API to query the list of regions
aliyun ecs describe-regions --accept-language en-US

Execute aliyun ecs --help para listar todos os comandos disponíveis. As seções a seguir abordam nomenclatura, instalação, parâmetros e recursos avançados.

Visão geral dos plugins

Cada plugin encapsula a API de um produto em nuvem em um executável independente. Principais recursos:

Instalação sob demanda: Instale apenas o necessário.
Atualizações independentes: Versionamento e lançamento separados da CLI.
Nomenclatura consistente: Comandos e parâmetros usam kebab-case (describe-instances, --accept-language).
Parâmetros simplificados: A CLI serializa parâmetros automaticamente. Use o mesmo formato chave-valor independentemente do estilo da API.
Ajuda integrada: Execute --help em qualquer comando para ver tipos de parâmetros, descrições e requisitos.

Os plugins ficam armazenados em ~/.aliyun/plugins e rastreados no arquivo manifest.json.

Convenção de nomenclatura de plugins

Os plugins seguem o formato de nomenclatura aliyun-cli-<ProductCode>, em que o código do produto corresponde à OpenAPI do Alibaba Cloud:

Nome	Código do produto	Produto em nuvem
`aliyun-cli-ecs`	`ecs`	Elastic Compute Service (ECS)
`aliyun-cli-fc`	`fc`	Function Compute (FC)
`aliyun-cli-rds`	`rds`	ApsaraDB RDS

Use o nome completo (aliyun-cli-ecs) ou o código do produto (ecs). Os nomes não diferenciam maiúsculas de minúsculas.

Instale plugins

Verifique a disponibilidade do plugin

Verifique se um produto em nuvem possui plugin disponível:

Consulta online (recomendado): Navegue por categoria, pesquise por palavra-chave e visualize exemplos de comandos no CLI Center.

Consulta via linha de comando: Liste os plugins disponíveis ou pesquise por palavra-chave:

Liste todos os plugins no índice remoto:
```
aliyun plugin list-remote
```

Exemplo de saída:

Total plugins available: 316

Name                                     Latest Version  Preview  Status         Local Version  Description
----                                     --------------  -------  ------         -------------  -----------
aliyun-cli-ecs                           0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for ECS operations.
aliyun-cli-fc                            0.1.0           No       Installed      0.1.0          Alibaba Cloud CLI plugin for FC 3.0 operations.
aliyun-cli-acc                           0.1.0           No       Not installed  -              Alibaba Cloud CLI plugin for acs operations.

Pesquise um plugin

Identifique qual plugin fornece um comando específico. Há suporte para correspondência de prefixo.

# Search for plugins containing "ecs"
aliyun plugin search ecs
# Search for commands in the ecs plugin that start with "describe"
aliyun plugin search "ecs describe"

Nota

Os plugins seguem o Versionamento Semântico (SemVer):
- Versões 0.x.x são experimentais e não possuem garantia de compatibilidade.
- Versões 1.0.0+ são estáveis dentro da mesma versão principal. Alterações na versão principal podem introduzir mudanças incompatíveis.
O índice remoto permanece em cache por uma hora. Para forçar a atualização, defina ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE=true.

Instale um plugin

O comando aliyun plugin install aceita um plugin via --name (ex.: aliyun plugin install --name ecs) ou como argumento posicional (ex.: aliyun plugin install ecs). Ambas as formas são equivalentes. A flag --name foi adicionada na versão 3.3.14.

Flag	Descrição
`--name <name>`	Instala um único plugin pelo nome. Disponível desde a v3.3.14. Mutuamente exclusiva com `--names` e `--package`.
`--names <name1> <name2> ...`	Instala um ou mais plugins pelo nome, separados por espaços. Mutuamente exclusiva com `--name` e `--package`.
`--version <version>`	Especifique a versão a instalar. Funciona apenas com `--name`. Se não especificada, instala-se a versão estável mais recente.
`--enable-pre`	Permite a instalação de versões de pré-lançamento.
`--package <path-or-url>`	Instala a partir de um arquivo compactado local (`.zip`, `.tar.gz`, `.tgz`) ou de uma URL que aponte para um arquivo compactado. Mutuamente exclusiva com `--name` e `--names`.
`--source-base <url>`	Usa uma URL de origem de plugin personalizada para este comando. Substitui as configurações de variáveis de ambiente e arquivos de configuração.

Exemplos:

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

# Install a specific version
aliyun plugin install --name fc --version 1.0.0

# Install multiple plugins at once
aliyun plugin install --names ecs rds vpc

# Install from a local archive file (for offline environments)
aliyun plugin install --package /path/to/ecs-plugin.zip

# Install from a URL
aliyun plugin install --package https://example.com/plugins/ecs-plugin.tar.gz

Verifique com aliyun plugin list:

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc       0.1.0               Aliyun CLI plugin for Function Compute 3.0 operations.

Nota

A CLI detecta automaticamente o sistema operacional e a arquitetura (darwin-arm64, linux-amd64) e baixa o pacote correspondente. Em instalações em lote, uma falha não bloqueia as demais. Plugins que exigem uma versão mais recente da CLI solicitam a atualização.

Visualize detalhes do plugin

Execute aliyun plugin list para listar os plugins instalados. Para visualizar detalhes de um plugin específico, execute:

aliyun plugin show --name ecs

Exemplo de saída:

Name:	              aliyun-cli-ecs
Version:	      0.3.0
Product code:	      Ecs
Short description:    Aliyun Ecs Plugin
Description:	      Aliyun CLI plugin for Elastic Compute Service operations.
API default:	      2014-05-26
API supported:	      2014-05-26

Campos:

Campo	Descrição
Name	Nome completo (ex.: `aliyun-cli-ecs`).
Version	Versão instalada.
Product code	Código do produto (ex.: `ecs`).
Short description	Breve resumo.
Description	Descrição completa.
API default version	Versão padrão da API para comandos.
API supported versions	Versões suportadas. Alterne com `--api-version`.
Inner	Indica se o plugin é interno.

Use plugins

Os comandos de plugin utilizam kebab-case. A CLI transmite credenciais, região e timeout do perfil atual automaticamente. Opções globais como --profile e --region aplicam-se sem configuração adicional.

Formato do comando:

aliyun <plugin-name> <Command> [--parameter-name value ...]

Exemplos de uso

Visualize a ajuda do plugin

Use aliyun <plugin-name> --help ou aliyun <plugin-name> <Command> --help. Por exemplo, liste todos os comandos do ecs:

aliyun ecs --help

Visualize detalhes dos parâmetros de um comando:

aliyun ecs describe-regions --help

Exemplo de saída:

......
  --accept-language         string, Filters the results by language. For more information, see[RFC
                            7231](https://tools.ietf.org/html/rfc7231). Valid values:
                            - zh-CN: Simplified Chinese.
                            - zh-TW: Traditional Chinese.
                            - en-US: English.
                            - ja: Japanese.
                            - fr: French.
                            - de: German.
                            - ko: Korean.
                            Default: en-US
  --instance-charge-type    string, The billing method for the instance. For more information, see https://help.aliyun.
                            com/document_detail/25398.html. Valid values:
                            - PrePaid: Subscription. If you use this method, make sure your account supports balance payments or credit payments.
                            Otherwise, an `InvalidPayMethod` error is reported.
                            - PostPaid: Pay-As-You-Go.
                            - SpotWithPriceLimit: A user-defined maximum price for a spot instance.
                            - SpotAsPriceGo: The system automatically bids for a spot instance at the Pay-As-You-Go price.
                            Default: PostPaid
......

A saída exibe o tipo, a descrição e a obrigatoriedade de cada parâmetro.

Consulte regiões

Consulte as regiões disponíveis:

aliyun ecs describe-regions --accept-language en-US

Exemplo de saída:

{
  "Regions": {
     "Region": [
	{
	   "LocalName": "China (Qingdao)",
	   "RegionEndpoint": "ecs.cn-qingdao.aliyuncs.com",
	   "RegionId": "cn-qingdao"
			},
	{
	   "LocalName": "China (Beijing)",
	   "RegionEndpoint": "ecs.cn-beijing.aliyuncs.com",
	   "RegionId": "cn-beijing"
	},
......

Uso avançado

Utilize parâmetros estruturados

Os plugins serializam parâmetros automaticamente. O formato de entrada permanece o mesmo, independentemente do estilo subjacente da API (repeatList, flat ou JSON):

Parâmetros de array: Repita a flag para cada valor (ex.: attribute-name).

aliyun ecs describe-account-attributes\
      --biz-region-id cn-hangzhou\
      --attribute-name max-security-groups\
      --attribute-name instance-network-type

Parâmetros de objeto: Use pares key=value (ex.: tag).

aliyun ecs describe-instances --biz-region-id cn-hangzhou\
       --tag key=env value=prod

Utilize APIs multiversão

Alguns produtos possuem múltiplas versões de API. Execute aliyun plugin list — plugins com suporte a múltiplas versões exibem multi-version na descrição:

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Alibaba Cloud CLI plugin for ECS operations.
aliyun-cli-ess      0.1.0               Alibaba Cloud CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc       0.1.0               Alibaba Cloud CLI plugin for FC 3.0 operations.

Use --api-version para selecionar uma versão específica:

Use a versão padrão da API

aliyun ess describe-scaling-groups --biz-region-id cn-hangzhou

Especifique uma versão da API usando --api-version

aliyun ess describe-scaling-groups --api-version 2022-02-22 --biz-region-id cn-hangzhou

Liste as versões de API suportadas
```
aliyun ess list-api-versions 
```

Defina uma versão padrão da API com uma variável de ambiente para evitar a repetição de --api-version. Formato: ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION (<PRODUCT_CODE> em maiúsculas):

# Add the environment variable and apply it
echo 'export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22' >> ~/.bashrc
source ~/.bashrc

A flag --api-version tem precedência sobre a variável de ambiente.

Atualize e desinstale plugins

Atualize um plugin

Atualize um plugin específico:

aliyun plugin update --name ecs

Atualize todos os plugins instalados:

aliyun plugin update

Se já estiver na versão mais recente, a CLI informará que nenhuma atualização é necessária. Adicione --enable-pre para versões de pré-lançamento.

Verifique com aliyun plugin list.

Desinstale um plugin

Remova um plugin:

aliyun plugin uninstall --name ecs

Verifique a remoção com aliyun plugin list.

Configure a instalação automática

A CLI pode instalar automaticamente plugins ausentes quando um comando os exigir. Esse recurso é útil para pipelines de CI/CD e ambientes com múltiplos produtos.

Ative a instalação automática

Ative via comando:

aliyun configure set --auto-plugin-install true

Ou com uma variável de ambiente:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc

Verifique com aliyun configure get.

Permita a instalação automática de pré-lançamentos:

aliyun configure set --auto-plugin-install-enable-pre true

Ou com uma variável de ambiente:

echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc

Política de instalação

O comportamento varia conforme o ambiente de execução:

Cenário	Comportamento
Instalação automática ativada	Instala automaticamente e continua a execução.
Terminal interativo com instalação automática desativada	Solicita confirmação antes de instalar.
Ambiente não interativo (script ou pipeline)	Exibe um aviso, mas não instala.

Exemplo de saída para instalação automática:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the automatic installation process
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Auto-installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Exemplo de saída em um ambiente interativo com instalação automática desativada:

# Run a command when the ecs plugin is not installed
aliyun ecs describe-regions --accept-language en-US
# Output of the interactive installation process
Plugin 'aliyun-cli-ecs' is required for command 'ecs describe-regions' but not installed.
Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.
Do you want to install it? [Y/n]: y
Installing plugin 'aliyun-cli-ecs' (including pre-release versions)...
Downloading aliyun-cli-ecs 0.1.0...
Plugin aliyun-cli-ecs 0.1.0 installed successfully!
......

Configurações globais de plugins

Use aliyun configure plugin-settings para definir uma origem personalizada de plugins em redes restritas ou para gerenciamento centralizado de URLs. As configurações ficam armazenadas em ~/.aliyun/plugin-settings.json.

Visualize as configurações atuais

Visualize as configurações atuais:

aliyun configure plugin-settings show

Defina uma origem personalizada de plugins

Defina uma URL de origem personalizada:

aliyun configure plugin-settings set --source-base https://internal-mirror.example.com/cli-plugins

Verifique:

aliyun configure plugin-settings show

Limpe as configurações personalizadas

Limpe as configurações personalizadas e restaure os padrões:

aliyun configure plugin-settings clear

Prioridade da URL de origem

A CLI resolve a URL de origem nesta ordem (a primeira correspondência prevalece):

A flag --source-base no comando atual.
A variável de ambiente ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE.
O valor source-base em ~/.aliyun/plugin-settings.json.
A URL padrão integrada.

Nota

As configurações de plugin ficam armazenadas em ~/.aliyun/plugin-settings.json.
Os subcomandos plugin-settings pertencem a aliyun configure, não a aliyun plugin.

Apêndice

Lista de comandos de plugin

Comando	Descrição
`aliyun plugin list`	Lista os plugins instalados.
`aliyun plugin show --name <name>`	Mostra detalhes de um plugin instalado.
`aliyun plugin list-remote`	Lista os plugins disponíveis no índice remoto.
`aliyun plugin search <command-name>`	Pesquisa o plugin correspondente a um comando.
`aliyun plugin install (--name	--names [ ...]	--package ) [--version ] [--enable-pre] [--source-base ]`	Instala um ou mais plugins.
`aliyun plugin update [--name <name>] [--enable-pre]`	Atualiza um plugin.
`aliyun plugin uninstall --name <name>`	Desinstala um plugin.
`aliyun configure plugin-settings show`	Exibe as configurações do sistema de plugins.
`aliyun configure plugin-settings set --source-base <url>`	Define a URL base de origem dos plugins.
`aliyun configure plugin-settings clear`	Remove a URL base de origem personalizada e reverte para o padrão integrado.

Variáveis de ambiente de plugins

Variáveis de ambiente para o comportamento dos plugins:

Variável de ambiente	Descrição
`ALIBABA_CLOUD_CLI_PLUGINS_DIR`	Diretório personalizado de plugins. Padrão: `~/.aliyun/plugins`.
`ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE`	Defina como `true` para desativar o cache do índice remoto.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL`	Defina como `true` para ativar a instalação automática.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE`	Defina como `true` para permitir a instalação automática de versões de pré-lançamento.
`ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE`	URL de origem personalizada de plugins. Equivalente a `--source-base` nos comandos `plugin install` e `plugin update`. Também configurável via `aliyun configure plugin-settings set`.
`ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION`	Versão padrão da API para um produto. Exemplo: `ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22`.
`ALIBABA_CLOUD_CLI_MAX_LINE_LENGTH`	Comprimento máximo de linha para a saída de ajuda.

FAQ

Falha na instalação: "no stable version available"

O plugin possui apenas versões de pré-lançamento. Adicione --enable-pre:

aliyun plugin install --name <plugin-name> --enable-pre