Skip to content

Latest commit

 

History

History
262 lines (176 loc) · 9.52 KB

README_zh.md

File metadata and controls

262 lines (176 loc) · 9.52 KB
Raw

阿里云命令行工具 (Alibaba Cloud Command Line Interface)

Build Status

阿里云命令行工具是开源项目，您可以从Github上获取最新版本的CLI。

该版本的CLI为Go语言重构版本，如果您想使用原有的Python版本(不推荐，已不提供支持)，请切换到Python分支。

简介

阿里云命令行工具是用Go语言编写的, 基于阿里云OpenAPI打造的，用于管理阿里云资源的工具。通过下载和配置该工具，您可以在一个命令行方式下使用多个阿里云产品。

如果您在使用SDK的过程中遇到任何问题，欢迎前往阿里云SDK问答社区提问，提问前请阅读提问引导。亦可在当前GitHub提交Issues。

注意：阿里云CLI使用OpenAPI方式访问云产品，确保您已经开通了要使用的云产品并了解该产品的OpenAPI的使用。您可以在阿里云API平台获取产品API文档，了解API的使用方式及参数列表。

安装阿里云CLI

您可以通过下载安装包或者直接编译源码的方式安装阿里云CLI：

  • 下载安装包 (推荐)

    阿里云CLI工具下载、解压后即可使用，支持Mac, Linux, Windows平台(x64版本)。 您可以将解压的aliyun可执行文件移至/usr/local/bin目录下，或添加到$PATH中。

    下载链接如下 (3.0.6)：

  • 编译源码

    如果您能访问golang.org, 并安装配置好Golang环境(go1.10.1)，请按照如下步骤下载源码并编译。

     $ mkdir -p $GOPATH/src/github.com/aliyun
 $ cd $GOPATH/src/github.com/aliyun
 $ git clone http://github.com/aliyun/aliyun-cli.git
 $ git clone http://github.com/aliyun/aliyun-openapi-meta.git
 $ cd aliyun-cli
 $ make install

配置阿里云CLI

在使用阿里云CLI前，您需要运行aliyun configure命令进行配置。在配置阿里云CLI时，您需要提供阿里云账号以及一对AccessKeyId和AccessKeySecret。

您可以在阿里云控制台的AccessKey页面创建和查看您的AccessKey，或者联系您的系统管理员获取AccessKey。

基本配置

$ aliyun configure
Configuring profile 'default' ...
Aliyun Access Key ID [None]: <Your AccessKey ID>
Aliyun Access Key Secret [None]: <Your AccessKey Secret>
Default Region Id [None]: cn-hangzhou
Default output format [json]: json
Default Languate [zh]: zh

多用户配置

阿里云CLI支持多用户配置。您可以使用$ aliyun configure --profile user1命令指定使用哪个账号调用OpenAPI。

执行$ aliyun configure list命令可以查看当前的用户配置, 如下表。 其中在Profile后面有星号（*）标志的为当前使用的默认用户配置。

Profile   | Credential         | Valid   | Region           | Language
--------- | ------------------ | ------- | ---------------- | --------
default * | AK:***f9b          | Valid   | cn-beijing       | zh
aaa       | AK:******          | Invalid |                  |
test      | AK:***456          | Valid   |                  | en
ecs       | EcsRamRole:EcsTest | Valid   | cn-beijing       | en

其他认证方式

阿里云CLI，可通过在configure命令后增加--mode <authenticationMethod>参数的方式来使用不同的认证方式，目前支持的认证方式如下：

验证方式 说明
AK 使用AccessKey ID/Secret访问
StsToken 使用STS Token访问
RamRoleArn 使用RAM子账号的AssumeRole方式访问
EcsRamRole 在ECS实例上通过EcsRamRole实现免密验证

启用zsh/bash自动补全

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

配置Pretty JSON

阿里云CLI返回的执行结果为Raw JSON。如需Pretty JSON，可安装jq工具，使用方式如下：

$ aliyun ecs DescribeRegions | jq

使用阿里云CLI

阿里云云产品的OpenAPI有RPC和RESTful两种风格，大部分产品使用的是RPC风格。不同风格的API的调用方法也不同。

您可以通过以下特点判断API风格：

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

####调用RPC风格的API

阿里云CLI中RPC风格的API调用的基本结构如下：

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

代码示例：

$ aliyun rds DescribeDBInstances --PageSize 50
$ aliyun ecs DescribeRegions
$ aliyun rds DescribeDBInstanceAttribute --DBInstanceId xxxxxx

调用RESTful风格的API

部分阿里云产品如容器服务的OpenAPI为Restful风格，调用Restful风格的接口与调用RPC风格的接口方式不同。参考以下代码示例，调用RESTful API。

  • GET请求示例：

     $ aliyun cs GET /clusters

  • POST请求示例：

     $ aliyun cs POST /clusters --body "$(cat input.json)"

  • DELETE请求示例：

     $ aliyun cs DELETE /clusters/ce2cdc26227e09c864d0ca0b2d5671a07

获取帮助信息

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

  • $ aliyun help: 获取产品列表

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

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

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

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

使用--force参数

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

$ 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结构化数据，不方便阅读。例如：

$ aliyun ecs DescribeInstances

执行以上命令将得到以下json结果：

{
  "PageNumber": 1,
  "TotalCount": 2,
  "PageSize": 10,
  "RequestId": "2B76ECBD-A296-407E-BE17-7E668A609DDA",
  "Instances": {
    "Instance": [
      {
        "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
        "InstanceTypeFamily": "ecs.xn4",
        "VlanId": "",
        "InstanceId": "i-12345678912345678123",
        "Status": "Stopped",
        //omit some fields
      },
      Instance": [
      {
        "ImageId": "ubuntu_16_0402_64_20G_alibase_20171227.vhd",
        "InstanceTypeFamily": "ecs.xn4",
        "VlanId": "",
        "InstanceId": "i-abcdefghijklmnopqrst",
        "Status": "Running",
        //omit some fields
      },
    ]
  }
}

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

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

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

InstanceId             | Status
----------             | ------
i-12345678912345678123 | Stopped
i-abcdefghijklmnopqrst | Running

在使用--output参数时，必须指定以下子参数：

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

可选子参数：

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

使用--waiter参数

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

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

例如：

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

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

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

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

可选子参数：

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