Alibaba Cloud CLI 3.3.0 dan versi yang lebih baru mendukung instalasi plugin produk cloud mandiri secara on-demand. Plugin ini memungkinkan Anda memanggil API melalui antarmuka baris perintah terpadu. Plugin tersebut mendukung pemuatan dinamis, serialisasi parameter otomatis, dan beberapa versi API. - Alibaba Cloud CLI

Alibaba Cloud CLI versi 3.3.0 dan yang lebih baru menggunakan arsitektur berbasis plugin yang memisahkan kemampuan baris perintah untuk setiap produk cloud ke dalam plugin mandiri. Pendekatan ini memungkinkan Anda hanya menginstal plugin yang diperlukan, memperbaruinya secara independen, dan menjaga CLI inti tetap ringan. Semua nama plugin menggunakan format kebab-case, dan CLI secara otomatis melakukan serialisasi parameter untuk menyederhanakan pemanggilan API.

Prasyarat

Cloud Assistant CLI versi 3.3.0 atau yang lebih baru telah diinstal. Untuk informasi selengkapnya, lihat Menginstal CLI (Linux).
Konfigurasikan kredensial untuk Alibaba Cloud CLI. Untuk informasi selengkapnya, lihat Konfigurasikan kredensial.

Panduan Cepat Mulai

Bagian ini menggunakan plugin ecs sebagai contoh untuk menunjukkan cara menginstal plugin dan menampilkan daftar wilayah yang tersedia.

# Instal plugin (contoh plugin ecs)
aliyun plugin install --names ecs

# Panggil API untuk menampilkan daftar wilayah
aliyun ecs describe-regions --accept-language zh-CN

Anda dapat menjalankan aliyun ecs --help untuk melihat semua perintah yang didukung oleh plugin ECS. Bagian selanjutnya menjelaskan konvensi penamaan plugin, instalasi dan manajemen, penggunaan parameter, serta fitur lanjutan.

Ikhtisar plugin

Plugin mengemas kemampuan pemanggilan API dari setiap produk cloud ke dalam program eksekusi mandiri yang diatur secara seragam oleh CLI inti. Fitur utamanya meliputi:

Instalasi sesuai kebutuhan: Anda hanya perlu menginstal plugin yang diperlukan untuk mengurangi ukuran CLI.
Pembaruan independen: Plugin merilis versi secara independen. Anda tidak perlu meningkatkan versi CLI inti.
Penamaan konsisten: Perintah dan parameter menggunakan format kebab-case, seperti describe-instances dan --accept-language.
Parameter disederhanakan: Parameter tingkat rendah secara otomatis diserialisasi. Anda dapat menggunakan pasangan kunci-nilai sebagai input.
Bantuan lengkap: Anda dapat menjalankan perintah --help untuk melihat tipe parameter, deskripsi, dan apakah parameter tersebut wajib diisi.

Plugin diinstal ke direktori ~/.aliyun/plugins. File manifest.json berisi daftar plugin yang telah diinstal.

Aturan penamaan plugin

Nama plugin mengikuti format aliyun-cli-<product-code>. Kode produk sama dengan kode produk pada Alibaba Cloud OpenAPI. Contohnya sebagai berikut:

Nama plugin	Kode produk	Produk cloud
`aliyun-cli-ecs`	`ecs`	Elastic Compute Service
`aliyun-cli-fc`	`fc`	Function Compute
`aliyun-cli-rds`	`rds`	ApsaraDB RDS

Anda dapat menggunakan nama plugin lengkap, seperti aliyun-cli-ecs, atau kode produk, seperti ecs, saat menginstal, menguninstal, atau memperbarui plugin. Nama-nama tersebut tidak peka huruf besar/kecil.

Instal plugin

Lihat dan cari plugin

Anda dapat melihat semua plugin yang tersedia di indeks remote:

aliyun plugin list-remote

Contoh output berikut dikembalikan:

Total plugins available: 316

Name                                     Latest Version  Preview  Status         Local Version  Description
----                                     --------------  -------  ------         -------------  -----------
aliyun-cli-ecs                           0.1.0           No       Installed      0.1.0          Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-fc                            0.1.0           No       Installed      0.1.0          Aliyun CLI plugin for Function Compute 3.0 operations.
aliyun-cli-acc                           0.1.0           No       Not installed  -              Aliyun CLI plugin for acs operations.

Untuk menemukan plugin yang berisi perintah tertentu, Anda dapat menggunakan fitur pencarian. Fitur pencarian ini mendukung pencocokan awalan.

# Cari plugin yang mengandung ecs
aliyun plugin search ecs
# Cari perintah yang diawali dengan describe pada produk ecs
aliyun plugin search "ecs describe"

Catatan

Plugin CLI mengikuti Semantic Versioning (SemVer). Versi 0.x.x bersifat eksperimental dan tidak menjamin kompatibilitas. Versi stabil dimulai dari 1.0.0. Kompatibilitas mundur dijamin dalam versi utama yang sama. Peningkatan versi utama dapat mengenalkan perubahan yang tidak kompatibel.
Secara default, indeks remote di-cache selama satu jam. Untuk memaksa penyegaran, Anda dapat mengatur variabel lingkungan ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE=true.

Jalankan instalasi

Jalankan perintah berikut untuk menginstal plugin:

aliyun plugin install --names ecs

Setelah instalasi selesai, Anda dapat menjalankan aliyun plugin list untuk mengonfirmasi hasilnya.

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.

Anda dapat menggunakan parameter opsional berikut sesuai kebutuhan:

Skenario	Contoh perintah	Deskripsi
Instal beberapa plugin sekaligus	`aliyun plugin install --names fc ecs`	Pisahkan nama dengan spasi
Instal versi tertentu	`aliyun plugin install --names fc --version 1.0.0`	Jika tidak ditentukan, instal versi stabil terbaru

Catatan

CLI secara otomatis mendeteksi sistem operasi dan arsitektur Anda, seperti darwin-arm64 dan linux-amd64, lalu mengunduh paket plugin yang sesuai. Jika instalasi plugin gagal selama instalasi batch, plugin lain tetap dapat diinstal. Beberapa plugin memerlukan versi CLI minimum. Jika versi CLI Anda tidak memenuhi persyaratan, CLI akan meminta Anda untuk melakukan upgrade.

Gunakan plugin

Plugin produk menggunakan penamaan kebab-case. CLI meneruskan kredensial, seperti AccessKey dan token Security Token Service, serta pengaturan wilayah dan timeout dari profil saat ini ke plugin. Opsi seperti --profile dan --region juga tersedia untuk perintah plugin. Anda tidak perlu melakukan konfigurasi terpisah.

Format perintahnya adalah sebagai berikut:

aliyun <product-code> <command> [--parameter-name value ...]

Contoh penggunaan

Lihat bantuan plugin

Anda dapat menjalankan aliyun <product-code> --help atau aliyun <product-code> <command> --help untuk melihat informasi bantuan. Misalnya, untuk menampilkan daftar semua perintah yang didukung oleh ecs, jalankan perintah berikut:

aliyun ecs --help

Anda dapat melihat parameter untuk perintah tertentu dalam plugin ecs:

aliyun ecs describe-regions --help

Contoh output:

......
  --accept-language         string, Filter results by Chinese, English, or Japanese. 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 value: zh-CN
  --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. Confirm your account supports balance payment or credit payment. Otherwise, the error InvalidPayMethod occurs.
                            - PostPaid: Pay-as-you-go.
                            - SpotWithPriceLimit: Set a maximum price.
                            - SpotAsPriceGo: Let the system set the bid. The highest price is the pay-as-you-go price.
                            Default value: PostPaid
......

Teks bantuan menampilkan tipe, deskripsi, dan apakah setiap parameter wajib diisi.

Daftar wilayah

Jalankan perintah berikut untuk menampilkan daftar wilayah:

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

Contoh output berikut dikembalikan:

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

Penggunaan lanjutan

Input parameter terstruktur

Plugin menangani serialisasi parameter secara otomatis. Anda dapat menggunakan metode input yang sama terlepas dari gaya parameter API, seperti repeatList, flat, atau JSON:

Parameter array: Jika suatu parameter menerima array, Anda dapat mengulang parameter tersebut. Misalnya, attribute-name.

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

Parameter objek: Gunakan format key=value untuk objek. Misalnya, tag.

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

Beberapa versi API

Beberapa produk cloud mendukung beberapa versi API. Anda dapat menjalankan aliyun plugin list untuk menampilkan daftar plugin yang telah diinstal. Plugin yang memiliki multi-version dalam deskripsinya mendukung beberapa versi API. Contohnya:

Name                Version             Description
----                -------             -----------
aliyun-cli-ecs      0.1.0               Aliyun CLI plugin for Elastic Compute Service operations.
aliyun-cli-ess      0.1.0               Aliyun CLI plugin for Auto Scaling operations with multi-version API support.
aliyun-cli-fc       0.1.0               Aliyun CLI plugin for Function Compute 3.0 operations.

Untuk plugin yang mendukung beberapa versi API, Anda dapat menggunakan parameter --api-version untuk menentukan versi yang ingin digunakan:

Gunakan versi API default:

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

Tentukan versi API menggunakan parameter --api-version:

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

Tampilkan daftar versi API yang didukung:
```
aliyun ess list-api-versions 
```

Jika Anda sering menggunakan versi API tertentu, Anda dapat mengaturnya sebagai versi default menggunakan variabel lingkungan. Dengan demikian, Anda tidak perlu menentukan parameter --api-version setiap kali menjalankan perintah. Format variabel lingkungan adalah ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION. Ganti <PRODUCT_CODE> dengan kode produk dalam huruf kapital. Contohnya:

# Tambahkan variabel lingkungan dan terapkan
echo 'export ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22' >> ~/.bashrc
source ~/.bashrc

Setelah Anda mengatur variabel lingkungan, perintah akan menggunakan versi API yang ditentukan secara default. Jika Anda menentukan parameter --api-version dalam suatu perintah, parameter tersebut akan mengambil prioritas dibandingkan variabel lingkungan.

Perbarui dan uninstal plugin

Perbarui plugin

Anda dapat memperbarui plugin tertentu:

aliyun plugin update --name ecs

Anda juga dapat memperbarui semua plugin yang telah diinstal.

aliyun plugin update

Jika plugin sudah mutakhir, CLI akan menunjukkan bahwa tidak diperlukan pembaruan. Untuk memperbarui plugin ke versi pra-rilis, Anda dapat menambahkan parameter --enable-pre.

Hapus instalan plugin

aliyun plugin uninstall --name ecs

Setelah operasi selesai, Anda dapat menjalankan aliyun plugin list untuk mengonfirmasi hasilnya.

Konfigurasikan instalasi plugin otomatis

Saat Anda menjalankan perintah untuk suatu produk cloud, CLI dapat secara otomatis menginstal plugin yang diperlukan jika belum diinstal. Anda dapat mengaktifkan fitur ini di lingkungan non-interaktif, seperti pipeline CI/CD atau skrip. Anda juga dapat mengaktifkan fitur ini jika menggunakan banyak produk cloud berbeda. Hal ini mencegah gangguan dan instalasi manual berulang.

Cara mengaktifkan

Anda dapat mengaktifkan fitur ini dengan menjalankan perintah berikut:

aliyun configure set --auto-plugin-install true

Atau, aktifkan dengan mengatur variabel lingkungan (contoh Linux):

# Tambahkan variabel lingkungan dan terapkan
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL=true' >> ~/.bashrc
source ~/.bashrc

Setelah Anda mengonfigurasi pengaturan, Anda dapat menjalankan aliyun configure get untuk memverifikasi konfigurasi.

Untuk mengaktifkan instalasi otomatis versi pra-rilis:

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

Atau konfigurasikan pengaturan menggunakan variabel lingkungan. Misalnya, pada Linux:

# Tambahkan variabel lingkungan dan terapkan
echo 'export ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE=true' >> ~/.bashrc
source ~/.bashrc

Strategi instalasi

Antarmuka baris perintah (CLI) memilih kebijakan berdasarkan lingkungan eksekusi.

Skenario	Perilaku
Instalasi otomatis diaktifkan	Instal plugin secara otomatis dan lanjutkan menjalankan perintah
Terminal interaktif dan instalasi otomatis dinonaktifkan	Meminta konfirmasi instalasi
Lingkungan non-interaktif (skrip, pipeline)	Menampilkan prompt instalasi tetapi tidak menginstal secara otomatis

Berikut adalah contoh output instalasi otomatis:

# Jalankan tanpa plugin ecs yang diinstal
aliyun ecs describe-regions --accept-language zh-CN
# Output instalasi otomatis
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!
......

Contoh output instalasi interaktif (instalasi otomatis dinonaktifkan):

# Jalankan tanpa plugin ecs yang diinstal
aliyun ecs describe-regions --accept-language zh-CN
# Output instalasi interaktif
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!
......

Lampiran

Referensi perintah plugin

Perintah	Deskripsi
`aliyun plugin list`	Daftar plugin yang telah diinstal
`aliyun plugin list-remote`	Daftar plugin remote yang tersedia
`aliyun plugin search <command-name>`	Cari plugin yang berisi perintah tertentu
`aliyun plugin install --names <name> [--version <version>] [--enable-pre]`	Instal plugin
`aliyun plugin update [--name <name>] [--enable-pre]`	Perbarui plugin
`aliyun plugin uninstall --name <name>`	Uninstal plugin

Variabel lingkungan plugin

Anda dapat menggunakan variabel lingkungan berikut untuk mengontrol perilaku plugin:

Variabel lingkungan	Deskripsi
`ALIBABA_CLOUD_CLI_PLUGINS_DIR`	Direktori plugin kustom. Default: `~/.aliyun/plugins`
`ALIBABA_CLOUD_CLI_PLUGIN_NO_CACHE`	Atur ke `true` untuk menonaktifkan caching indeks remote
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL`	Atur ke `true` untuk mengaktifkan instalasi otomatis
`ALIBABA_CLOUD_CLI_PLUGIN_AUTO_INSTALL_ENABLE_PRE`	Atur ke `true` untuk mengizinkan instalasi otomatis versi pra-rilis
`ALIBABA_CLOUD_<PRODUCT_CODE>_API_VERSION`	Atur versi API default untuk plugin produk. Contoh: `ALIBABA_CLOUD_ESS_API_VERSION=2022-02-22`
`ALIBABA_CLOUD_CLI_MAX_LINE_LENGTH`	Atur panjang baris untuk teks bantuan parameter.

FAQ

Instalasi plugin menampilkan “no stable version available”

Pesan ini menunjukkan bahwa hanya versi pra-rilis yang tersedia untuk plugin tersebut. Untuk menginstal versi pra-rilis, Anda dapat menambahkan parameter --enable-pre ke perintah instalasi:

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