edit-icon download-icon

Use CLI

Last Updated: May 05, 2019

Alibaba Cloud offers two different types of APIs: RPC APIs and RESTful APIs. Most of products, like ECS, RDS, and so on, provide RPC APIs. Products, like Resource Orchestration Service and Container Service, provide REST APIs.

You can distinguish the API style from the following characteristics:

  • The API requiring the Action parameter is an RPC API, while the API requiring the PathPattern parameter is a RESTful style.
  • In general, the API style for a product is consistent.
  • Each API only supports one style. If an incorrect calling method is used, an error ApiNotFound is returned.

Call RPC APIs

The following statement shows how to call RPC APIs using the Alibaba Cloud CLI:

  1. $ aliyun <product> <operation> --parameter1 value1 --parameter2 value2 ...

Examples:

  1. $ aliyun rds DescribeDBInstances --PageSize 50
  2. $ aliyun ecs DescribeRegions
  3. $ aliyun rds DescribeDBInstanceAttribute --DBInstanceId xxxxxx

Call RESTful APIs

APIs of some products such as Container Service are RESTful style. The way to call RESTful APIs is different from RPC APIs.

The following examples show how to call RESTful APIs using the Alibaba Cloud CLI:

  • GET request:

    1. $ aliyun cs GET /clusters
  • POST request:

    1. $ aliyun cs POST /clusters --body "$(cat input.json)"
  • DELETE request:

    1. $ aliyun cs DELETE /clusters/ce2cdc26227e09c864d0ca0b2d5671a07

force option

Alibaba Cloud CLI integrates the product metadata of some products. The CLI validates the API parameters when calling an API. If an API or a parameter that is not included in the metadata is used, an error unknown api or unknown parameter will be returned. You can use the --force option to skip the validation and call the API by force as shown in the following example:

  1. $ aliyun newproduct --version 2018-01-01 --endpoint newproduct.aliyuncs.com --param1 ... --force

The following two parameters are required when using the --force option:

  • --version: The API version.

    You can find the API version in the API documentation. For example, the ECS API version is 2014-05-26.

  • --endpoint: The service endpoint of the product.

    Most of the product endpoints are in the format of product.aliyuncs.com, while some products are using product.en-central-1.aliyuncs.com. Obtain the product endpoint in the corresponding API documentation.

output option

By default, the output from the Alibaba Cloud CLI is in the JSON format. You can use the --output option to format the output.

After running the aliyun ecs DescribeInstances command, the following output is returned by default:

  1. {
  2. "PageNumber": 1,
  3. "TotalCount": 2,
  4. "PageSize": 10,
  5. "RequestId": "2B76ECBD-A296-407E-BE17-7E668A609DDA",
  6. "Instances": {
  7. "Instance": [
  8. {
  9. "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
  10. "InstanceTypeFamily": "ecs.xn4",
  11. "VlanId": "",
  12. "InstanceId": "i-12345678912345678123",
  13. "Status": "Stopped",
  14. //omit some fields
  15. },
  16. Instance": [
  17. {
  18. "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
  19. "InstanceTypeFamily": "ecs.xn4",
  20. "VlanId": "",
  21. "InstanceId": "i-abcdefghijklmnopqrst",
  22. "Status": "Running",
  23. //omit some fields
  24. },
  25. ]
  26. }
  27. }

You can use --output option to filter specific output parameters with the table format as shown in the following example.

Command syntax:

  1. $ aliyun ecs DescribeInstances --output cols=InstanceId,Status

Output:

  1. InstanceId | Status
  2. ---------- | ------
  3. i-12345678912345678123 | Stopped
  4. i-abcdefghijklmnopqrst | Running

The following parameters are required when the --output option is used:

  • cols(required): The column name.

    It must be the output parameters. For example, you can use the output parameters InstanceId and Status of the DescribeInstances API as the column name.

  • rows (optional): Specify the data source of a table row using the jmespath query statement. This parameter can be omitted when Instances.Instance[] is used.

waiter option

You can use the --waiter option to query the instance information until the specified state occurs.

For example, the ECS instance will be started after it is created. You can use the --option to know whether the ECS instance is started.

The following command will query the ECS instance status at regular intervals until the ECS instance is running.

  1. $ aliyun ecs DescribeInstances --InstanceIds '["i-12345678912345678123"]' --waiter expr='Instances.Instance[0].Status' to=Running

The following parameters are required when the --waiter option is used:

  • expr: The field to query that is specified using jmespath.
  • to: The value of the query result.

The following are optional parameters that can be used with the --waiter option:

  • timeout: The timeout value in seconds.
  • interval: The interval in seconds between two consecutive queries.

Enable bash/zsh auto completion

Use the following commands to enable and disable auto completion when using the CLI:

  • Use aliyun auto-completion command to enable auto completion in zsh/bash
  • Use aliyun auto-completion --uninstall command to disable auto completion.

Get help information

Alibaba Cloud CLI integrates API descriptions for some products, you can get help by using the following commands:

  • aliyun help: get product list.

  • aliyun help <product>: get help API information of a specific product.

    For example, get help of ECS APIs: $ aliyun help ecs

  • $ aliyun help <product> <apiName>: get the detailed API descriptions of a specific API.

    For example, get the help information of the CreateInstance API: aliyun help ecs CreateInstance

© 2009-2020 Copyright by Alibaba Cloud. All rights reserved.