全部产品
云市场

使用CLI

更新时间:2018-09-12 23:20:52

阿里云云产品的API分为RPC和RESTful两种类型,大部分产品使用的是RPC风格。不同风格的API的调用方法也不同。

您可以通过以下特点判断API类型:

  • API参数中包含Action字段的是RPC API,需要PathPattern参数的是Restful API。
  • 一般情况下,每个产品内,所有API的调用风格是统一的。
  • 每个API仅支持特定的一种风格,传入错误的标识,可能会调用到其他API,或收到ApiNotFound的错误信息。

调用RPC API

使用阿里云CLI调用RPC API的基本结构如下:

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

代码示例:

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

调用RESTful API

部分阿里云产品如容器服务是RESTful API。RESTful API与RPC API的调用方式不同。

使用阿里云CLI调用RESTful API的基本结构如下:

  • GET请求

    请求结构:

    1. $ aliyun 云产品code GET /资源

    示例代码:

    1. $ aliyun cs GET /clusters
  • POST请求

    请求结构:

    1. $ aliyun 云产品code POST /资源 --body "$(cat input.json)"

    示例代码:

    1. aliyun cs POST /clusters/<cluster_id>/attach --header "Content-Type=application/json" --body "$(cat attach.json)"
  • DELETE请求

    请求结构:

    1. $ aliyun 云产品code GET /资源

    示例代码:

    1. $ aliyun cs DELETE /clusters/ce2cdc26227e09c864d0ca0b2d5671a07

force参数

阿里云CLI集成了部分云产品的元数据,在调用时会对参数的合法性进行检查。如果使用了一个元数据中未包含的API或参数会导致unknown apiunknown parameter错误。可以使用--force参数跳过API和参数检查,强制调用元数据列表外的API和参数,如:

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

在使用--force参数时,必须指定以下两个参数:

  • --version: 指定API的版本,你可以在API文档中找到版本号,如ECS的版本号是2014-05-26
  • --endpoint: 指定产品的接入地址,一般产品接入地址是product.aliyuncs.com,或product.en-central-1.aliyuncs.com,请参考各产品的API文档。

output参数

阿里云产品的查询接口会返回JSON结构化数据,不方便阅读。例如:

  1. $ aliyun ecs DescribeInstances

执行以上命令将得到以下JSON结果:

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

可以使用--output参数提取结果中感兴趣的字段,并进行表格化输出。例如:

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

执行以上命令将得到以下形式的结果:

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

在使用--output参数时,必须指定以下子参数:

  • cols: 表格的列名,需要与json数据中的字段相对应。如ECS DescribeInstances 接口返回结果中的字段InstanceId 以及 Status

可选子参数:

  • rows: 通过jmespath查询语句来指定表格行在json结果中的数据来源。当查询语句具有Instances.Instance[]的形式时,可以省略该参数。

waiter参数

该参数用于轮询实例信息直到出现特定状态。

例如使用ECS创建实例后,实例会有启动的过程。我们会不断的查询实例的运行状态,直到状态变为”Running”。

例如:

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

执行以上命令后,命令行程序将以一定时间间隔进行实例状态轮询,并在实例状态变为Running时停止轮询。

在使用--waiter参数时,必须指定以下两个子参数:

  • expr: 通过jmespath查询语句来指定json结果中的被轮询字段。
  • to: 被轮询字段的目标值。

可选子参数:

  • timeout: 轮询的超时时间(秒)。
  • interval: 轮询的间隔时间(秒)。

启用zsh/bash自动补全

您可以通过以下命令开启或关闭自动补全功能:

  • 使用aliyun auto-completion命令开启自动补全,目前支持zsh/bash。
  • 使用aliyun auto-completion --uninstall命令关闭自动补全。

获取帮助信息

阿里云CLI集成了部分产品的API和参数列表信息, 您可以使用如下命令获取帮助:

  • $ aliyun help: 获取产品列表

  • $ aliyun help <product>: 获取产品的API信息

    如获取ECS的API信息:$ aliyun help ecs

  • $ aliyun help <product> <apiName>: 获取API的调用信息

    如获取ECS的CreateInstance的信息: aliyun help ecs CreateInstance