Install and manage Alibaba Cloud CLI plugins | parameter serialization - Alibaba Cloud CLI

Ön koşullar

Alibaba Cloud CLI 3.3.0 veya sonraki bir sürümü yüklediniz. Yükleme talimatları için bkz. Alibaba Cloud CLI'yı yükleme, güncelleme ve kaldırma.
Alibaba Cloud CLI için kimlik bilgilerini yapılandırdınız. Talimatlar için bkz. Kimlik bilgilerini yapılandırma ve yönetme.

Hızlı başlangıç

Bu örnekte ecs eklentisi yüklenir ve bölgeler sorgulanır:

# 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

Kullanılabilir tüm komutları listelemek için aliyun ecs --help komutunu çalıştırın. Aşağıdaki bölümlerde adlandırma, yükleme, parametreler ve gelişmiş özellikler ele alınmaktadır.

Eklentilere genel bakış

Her eklenti, bir cloud ürününün API'sini bağımsız bir yürütülebilir dosya olarak sarar. Temel özellikler şunlardır:

Talep üzerine yükleme: Yalnızca ihtiyaç duyduklarınızı yükleyin.
Bağımsız güncellemeler: Sürümlendirilir ve CLI'dan ayrı olarak yayımlanır.
Tutarlı adlandırma: Komutlar ve parametreler kebab-case biçimini kullanır (describe-instances, --accept-language).
Basitleştirilmiş parametreler: CLI parametreleri otomatik olarak serileştirir; API stilinden bağımsız olarak aynı anahtar-değer biçimini kullanın.
Yerleşik yardım: Parametre türleri, açıklamaları ve gereksinimleri için herhangi bir komutta --help seçeneğini çalıştırın.

Eklentiler ~/.aliyun/plugins dizininde depolanır ve manifest.json dosyasında izlenir.

Eklenti adlandırma kuralı

Eklentiler aliyun-cli-<ProductCode> adlandırma biçimini takip eder; burada ürün kodu Alibaba Cloud OpenAPI ile eşleşir:

Ad	Ürün kodu	Cloud ürünü
`aliyun-cli-ecs`	`ecs`	Elastic Compute Service (ECS)
`aliyun-cli-fc`	`fc`	Function Compute (FC)
`aliyun-cli-rds`	`rds`	ApsaraDB RDS

Tam adı (aliyun-cli-ecs) veya ürün kodunu (ecs) kullanabilirsiniz. Adlar büyük/küçük harfe duyarlı değildir.

Eklentileri yükleme

Eklenti kullanılabilirliğini denetleme

Bir cloud ürününün eklentisinin olup olmadığını denetleyin:

Çevrimiçi sorgu (önerilen): CLI Center üzerinden kategoriye göre göz atın, anahtar kelimeyle arama yapın ve komut örneklerini görüntüleyin.

Komut satırı sorgusu: Kullanılabilir eklentileri listeleyin veya anahtar kelimeyle arama yapın:

Uzak dizindeki tüm eklentileri listeleyin:
```
aliyun plugin list-remote
```

Örnek çıktı:

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.

Eklenti arama

Belirli bir komutu sağlayan eklentiyi bulun. Önek eşleştirme desteklenir.

# 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"

Not

Eklentiler Anlamsal Sürümlemeyi (SemVer) takip eder:
- 0.x.x sürümleri deneyseldir ve uyumluluk garantisi verilmez.
- 1.0.0+ sürümleri, aynı ana sürüm içinde kararlıdır. Ana sürüm artışları kesintili değişiklikler içerebilir.
Uzak dizin bir saat süreyle önbelleğe alınır. Yenilemeyi zorlamak için ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE=true ayarlayın.

Eklenti yükleme

aliyun plugin install komutu, bir eklentiyi --name seçeneğiyle (ör. aliyun plugin install --name ecs) veya konumsal bir bağımsız değişkenle (ör. aliyun plugin install ecs) kabul eder. İkisi de eşdeğerdir. --name v3.3.14'te eklenmiştir.

Seçenek	Açıklama
`--name <name>`	Tek bir eklentiyi ada göre yükler. v3.3.14'ten itibaren kullanılabilir. `--names` ve `--package` ile birlikte kullanılamaz.
`--names <name1> <name2> ...`	Bir veya daha fazla eklentiyi boşlukla ayrılmış şekilde ada göre yükler. `--name` ve `--package` ile birlikte kullanılamaz.
`--version <version>`	Yüklenecek sürümü belirtir. Yalnızca `--name` ile çalışır. Belirtilmezse en son kararlı sürüm yüklenir.
`--enable-pre`	Ön sürüm sürümlerinin yüklenmesine izin verir.
`--package <path-or-url>`	Yerel bir arşiv dosyasından (`.zip`, `.tar.gz`, `.tgz`) veya bir arşivi işaret eden bir URL'den yükler. `--name` ve `--names` ile birlikte kullanılamaz.
`--source-base <url>`	Bu komut için özel bir eklenti kaynak URL'si kullanır. Ortam değişkeni ve yapılandırma dosyası ayarlarını geçersiz kılar.

Örnekler:

# 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

aliyun plugin list ile doğrulayın:

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.

Not

CLI, işletim sistemini ve mimariyi (darwin-arm64, linux-amd64) otomatik olarak algılar ve eşleşen paketi indirir. Toplu yüklemelerde bir hata diğerlerini engellemez. Daha yeni bir CLI sürümü gerektiren eklentiler sizi yükseltme konusunda uyarır.

Eklenti ayrıntılarını görüntüleme

Yüklenen eklentileri listelemek için aliyun plugin list komutunu çalıştırın. Belirli bir eklentinin ayrıntılarını görüntülemek için şu komutu çalıştırın:

aliyun plugin show --name ecs

Örnek çıktı:

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

Alanlar:

Alan	Açıklama
Name	Tam ad (ör. `aliyun-cli-ecs`).
Version	Yüklenen sürüm.
Product code	Ürün kodu (ör. `ecs`).
Short description	Kısa özet.
Description	Tam açıklama.
API default version	Komutlar için varsayılan API sürümü.
API supported versions	Desteklenen sürümler. `--api-version` ile değiştirin.
Inner	Eklentinin dahili bir eklenti olup olmadığı.

Eklentileri kullanma

Eklenti komutları kebab-case biçimini kullanır. CLI, kimlik bilgilerini, bölgeyi ve zaman aşımını geçerli profilden otomatik olarak iletir. --profile ve --region gibi genel seçenekler ek yapılandırma olmadan uygulanır.

Komut biçimi:

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

Kullanım örnekleri

Eklenti yardımını görüntüleme

aliyun <plugin-name> --help veya aliyun <plugin-name> <Command> --help kullanın. Örneğin, tüm ecs komutlarını listelemek için:

aliyun ecs --help

Bir komut için parametre ayrıntılarını görüntüleyin:

aliyun ecs describe-regions --help

Örnek çıktı:

......
  --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
......

Çıktı, her parametrenin türünü, açıklamasını ve gerekli olup olmadığını gösterir.

Bölgeleri sorgulama

Kullanılabilir bölgeleri sorgulayın:

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

Örnek çıktı:

{
  "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"
	},
......

Gelişmiş kullanım

Yapılandırılmış parametreleri kullanma

Eklentiler parametreleri otomatik olarak serileştirir. Giriş biçimi, temel alınan API stilinden (repeatList, flat veya JSON) bağımsız olarak aynıdır:

Dizi parametreleri: Her değer için seçeneği tekrarlayın (ör. attribute-name).

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

Nesne parametreleri: key=value çiftlerini kullanın (ör. tag).

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

Çok sürümlü API'leri kullanma

Bazı ürünlerin birden çok API sürümü vardır. aliyun plugin list komutunu çalıştırın; çok sürümlü desteği olan eklentiler açıklamalarında multi-version ifadesini gösterir:

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.

Belirli bir sürümü seçmek için --api-version seçeneğini kullanın:

Varsayılan API sürümünü kullanma

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

--api-version kullanarak bir API sürümü belirtme

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

Desteklenen API sürümlerini listeleme
```
aliyun ess list-api-versions 
```

--api-version seçeneğini tekrarlamaktan kaçınmak için varsayılan bir API sürümünü ortam değişkeniyle ayarlayın. Biçim: ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION (<PRODUCT_CODE> büyük harfle):

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

--api-version seçeneği, ortam değişkenine göre önceliklidir.

Eklentileri güncelleme ve kaldırma

Eklentiyi güncelleme

Belirli bir eklentiyi güncelleyin:

aliyun plugin update --name ecs

Yüklenen tüm eklentileri güncelleyin:

aliyun plugin update

Zaten en son sürümdeyse CLI güncelleme gerekmediğini bildirir. Ön sürüm sürümleri için --enable-pre ekleyin.

aliyun plugin list ile doğrulayın.

Eklentiyi kaldırma

Bir eklentiyi kaldırın:

aliyun plugin uninstall --name ecs

Kaldırmayı aliyun plugin list ile doğrulayın.

Otomatik yüklemeyi yapılandırma

CLI, bir komutun ihtiyaç duyduğunda eksik eklentileri otomatik olarak yükleyebilir; bu durum CI/CD işlem hatları ve çok ürün ortamları için kullanışlıdır.

Otomatik yüklemeyi etkinleştirme

Komutla etkinleştirin:

aliyun configure set --auto-plugin-install true

Veya ortam değişkeniyle:

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

aliyun configure get ile doğrulayın.

Ön sürüm otomatik yüklemesine izin verin:

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

Veya ortam değişkeniyle:

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

Yükleme ilkesi

Davranış çalışma zamanı ortamına göre değişir:

Senaryo	Davranış
Otomatik yükleme etkin	Otomatik olarak yükler ve devam eder.
Otomatik yükleme devre dışı bırakılmış etkileşimli terminal	Yüklemeye başlamadan önce sorar.
Etkileşimsiz ortam (betik veya işlem hattı)	Bir istem görüntüler ancak yüklemez.

Otomatik yükleme için örnek çıktı:

# 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!
......

Otomatik yükleme devre dışı bırakılmış etkileşimli ortamda örnek çıktı:

# 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!
......

Eklenti genel ayarları

Kısıtlı ağlar veya merkezi URL yönetimi için özel bir eklenti kaynağı ayarlamak üzere aliyun configure plugin-settings komutunu kullanın. Ayarlar ~/.aliyun/plugin-settings.json dosyasında depolanır.

Geçerli ayarları görüntüleme

Geçerli ayarları görüntüleyin:

aliyun configure plugin-settings show

Özel eklenti kaynağı ayarlama

Özel bir kaynak URL'si ayarlayın:

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

Doğrulayın:

aliyun configure plugin-settings show

Özel ayarları temizleme

Özel ayarları temizleyin ve varsayılanlara dönün:

aliyun configure plugin-settings clear

Kaynak URL önceliği

CLI kaynak URL'sini şu sırayla çözümler (ilk eşleşme kazanır):

Geçerli komuttaki --source-base seçeneği.
ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE ortam değişkeni.
~/.aliyun/plugin-settings.json dosyasındaki source-base değeri.
Yerleşik varsayılan URL.

Not

Eklenti ayarları ~/.aliyun/plugin-settings.json dosyasında depolanır.
plugin-settings alt komutları aliyun plugin yerine aliyun configure komutuna aittir.

Ek bilgi

Eklenti komut listesi

Komut	Açıklama
`aliyun plugin list`	Yüklenen eklentileri listeler.
`aliyun plugin show --name <name>`	Yüklenen bir eklentinin ayrıntılarını gösterir.
`aliyun plugin list-remote`	Uzak dizindeki kullanılabilir eklentileri listeler.
`aliyun plugin search <command-name>`	Bir komuta karşılık gelen eklentiyi arar.
`aliyun plugin install (--name <name> \| --names <name1> [<name2> ...] \| --package <path-or-url>) [--version <version>] [--enable-pre] [--source-base <url>]`	Bir veya daha fazla eklenti yükler.
`aliyun plugin update [--name <name>] [--enable-pre]`	Bir eklentiyi günceller.
`aliyun plugin uninstall --name <name>`	Bir eklentiyi kaldırır.
`aliyun configure plugin-settings show`	Eklenti sistem ayarlarını görüntüler.
`aliyun configure plugin-settings set --source-base <url>`	Eklenti kaynak temel URL'sini ayarlar.
`aliyun configure plugin-settings clear`	Özel kaynak temel URL'sini kaldırır ve yerleşik varsayılana döner.

Eklenti ortam değişkenleri

Eklenti davranışı için ortam değişkenleri:

Ortam değişkeni	Açıklama
`ALIBABA_CLOUD_CLI_PLUGINS_DIR`	Özel eklenti dizini. Varsayılan: `~/.aliyun/plugins`.
`ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE`	Uzak dizin önbelleğini devre dışı bırakmak için `true` olarak ayarlayın.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL`	Otomatik yüklemeyi etkinleştirmek için `true` olarak ayarlayın.
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE`	Ön sürüm sürümlerin otomatik yüklenmesine izin vermek için `true` olarak ayarlayın.
`ALIBABA_CLOUD_CLI_PLUGIN_SOURCE_BASE`	Özel eklenti kaynak URL'si. `plugin install` ve `plugin update` komutlarında `--source-base` seçeneğine eşdeğerdir. `aliyun configure plugin-settings set` aracılığıyla da ayarlanabilir.
`ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION`	Bir ürün için varsayılan API sürümü. Örnek: `ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22`.
`ALIBABA_CLOUD_CLI_MAX_LINE_LENGTH`	Yardım çıktısı için maksimum satır uzunluğu.

SSS

Yükleme başarısız: "no stable version available"

Eklentinin yalnızca ön sürüm sürümleri var. --enable-pre ekleyin:

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