云 API 使用 TCCLI

腾讯云 TCCLI 包含基础功能和高级功能，请参见下表：

一、安装 TCCLI

1. 安装 Python 环境和 pip 工具，安装命令行工具前请确保你的系统已经安装了 Python 环境和 pip 工具。详情请参见 Python SDK 文档。

2. Windows 系统按 Win+R 打开运行窗口输入 cmd 并单击确定，这篇以 Linux 为例。

3. 在命令行窗口中，执行以下命令进行 TCCLI 安装。

pip install tccli

注意：3.0.252.3以下版本升级需要执行以下代码：

注意：sudo pip uninstall tccli jmespathsudo pip install tccli

4. 执行以下命令，查看 TCCLI 是否安装成功。

tccli –version

返回类似如下结果，则说明已成功安装 TCCLI。

[root@VM_180_248_centos ~]# tccli –version3.0.250.1

5. 在 Linux 环境中，执行以下命令启动自动补全功能，支持大小写自动纠错：

complete -C 'tccli_completer' tccli

以下代码片段展示自动补全过程：

[root@VM_33_50_centos ~]# tccli ccam cbs cdn chdfs ckafka cloudhsm cms cr cynosdb captcha ccc cds cim clb cme configure cvm cat cdb cfs cis cloudaudit cmq cpdp cws [root@VM_33_50_centos ~]# tccli cvm RRebootInstances ResetInstance ResetInstancesType RenewHosts ResetInstancesInternetMaxBandwidth ResizeInstanceDisks RenewInstances ResetInstancesPassword RunInstances [root@VM_33_50_centos ~]# tccli cvm RunInstances —-ActionTimer –generate-cli-skeleton –InstanceType –SecurityGroupIds –ClientToken –HostName –InternetAccessible –SystemDisk –cli-input-json –HpcClusterId –LoginSettings –TagSpecification –DataDisks –ImageId –output –timeout –DisasterRecoverGroupIds –InstanceChargePrepaid –Placement –UserData –DryRun –InstanceChargeType –profile –version –endpoint –InstanceCount –region –VirtualPrivateCloud –EnhancedService –InstanceMarketOptions –secretId –filter –InstanceName –secretKey [root@VM_33_50_centos ~]# tccli cvm RunInstances –Placement

注意：说明：

注意：你也可以将该命令加入环境变量（/etc/profile）中，使自动补全功能一直有效。

二、配置 TCCLI

1. 在命令行中执行以下命令，进入交互模式快配置。

tccli configure

返回结果如下，请参考以下信息进行配置：

TencentCloud API secretId [*afcQ]: TencentCloud API secretKey [*ArFd]: region: output[json]:

·secretId：云 API 密钥 SecretId，请前往 API 密钥管理 获取（一个主账号最多可以申请两个云 API 密钥）。

·secretKey：云 API 密钥 SecretKey，请前往 API 密钥管理 获取。

·region：云产品地域，请前往对应云产品的 API 文档 获取可用的 region。例如云服务器的 地域列表。

·output：可选参数，请求回包输出格式，支持 JSON、table 及 text 三种格式，默认为 JSON。

2. 你可执行以下命令进入命令行模式，通过命令行模式你可以在自动化脚本中配置你的信息。

# set子命令可以设置某一配置，也可同时配置多个。 tccli configure set secretId ************ tccli configure set region ap-guangzhou output json # get子命令用于获取配置信息。 tccli configure get secretKey secretKey = ************ # list子命令打印所有配置信息。 tccli configure list credential: secretId = ************ secretKey = ************ configure: region = ap-guangzhou output = json

3. 你可执行以下命令配置多账户支持，方便你在多种配置同时使用。

# 在交互模式中指定账户名 test。 $ tccli configure –profile test TencentCloud API secretId [*BCDP]:************ TencentCloud API secretKey [*ArFd]:************ region: ap-guangzhou output[json]: # set/get/list子命令指定账户名 test。此命令与上条命令作用相同 $ tccli configure set region ap-guangzhou output json secretId ************ secretKey ************ –profile test # 已可以修改单独一个，例如修改地域： $ tccli configure set region ap-beijing # 查看test用户密钥key或查看配置, 使用命令如下： $ tccli configure get secretKey –profile test $ tccli configure list –profile test # 在调用接口时指定账户（以 cvm DescribeZones 接口为例）。 $ tccli cvm DescribeZones –profile test

4. 你可以通过以下两种方式配置 HTTPS 代理，使 TCCLI 通过代理调用 API。

·在环境变量中配置 HTTPS 代理：

# 在Linux/Unix和macOS中执行如下类似命令配置环境变量export https_proxy=https://192.168.1.1:1111export https_proxy=https://myproxy.com:1111# 在Windows的终端中执行如下类似命令配置环境变量setx http_proxy=https://192.168.1.1:1111set http_proxy=https://myproxy.com:1111# setx表示设置永久环境变量，设置后重启终端生效

·在命令行中使用 –https-proxy 选项设置 HTTPS 代理：

# 例如tccli cvm DescribeRegions –https-proxy https://192.168.1.1:1111

三、基础功能

TCCLI 支持自主配置，helper 信息支持中文信息且支持 JSON、table 及 text 输出格式。

注意：示例中非简单类型的参数必须为标准 JSON 格式。

TCCLI 目前支持以下三种调用方式：

·JSON 字符串入参调用

·JSON 文件入参调用 (–cli-input-json)

·复杂类型点（.）连接展开形式入参调用 (–cli-unfold-argument)

四、JSON 字符串入参调用示例

·执行以下命令，创建一台 CVM。

$ tccli cvm RunInstances –InstanceChargeType POSTPAID_BY_HOUR –InstanceChargePrepaid '{"Period":1,"RenewFlag":"DISABLE_NOTIFY_AND_MANUAL_RENEW"}' –Placement '{"Zone":"ap-guangzhou-5"}' –InstanceType S1.SMALL1 –ImageId img-8toqc6s3 –SystemDisk '{"DiskType":"CLOUD_BASIC", "DiskSize":50}' –InternetAccessible '{"InternetChargeType":"TRAFFIC_POSTPAID_BY_HOUR","InternetMaxBandwidthOut":10,"PublicIpAssigned":true}' –InstanceCount 1 –InstanceName TCCLI-TEST –LoginSettings '{"Password":"isd@cloud"}' –SecurityGroupIds '["sg-0rszg2vb"]' –HostName TCCLI-HOST-NAME1

·执行以下命令，获取 CVM 的监控数据。

[root@VM_33_50_centos ~]# tccli monitor GetMonitorData –Namespace "QCE/CVM" –Period 300 –MetricName "CPUUsage" –Instances '[{"Dimensions":[{"Name":"InstanceId","Value":"ins-cac6a4w8"}]}]'

五、JSON 文件入参调用（–cli-input-json）示例

1. 执行以下命令，输出入参数据结构到 JSON 文件。

[root@VM_33_50_centos ~]# tccli cvm RunInstances –generate-cli-skeleton > /tmp/RunInstances.json

2. 将文件中参数值替换为实际使用值，并使用该 JSON 文件作为入参，格式为 –cli-input-json 后接 file://+文件路径。示例如下：

[root@VM_33_50_centos ~]# tccli cvm RunInstances –cli-input-json file:///tmp/RunInstances.json{ "RequestId": "20e2b42d-3260-4750-9293-79116208330e", "InstanceIdSet": null}

六、复杂类型点（.）连接展开形式入参调用（–cli-unfold-argument）示例

复杂类型点连接展开调用是将复杂类型按用点连接的形式展开，此方式可充分利用命令行自动补全机制来解决入参较复杂时的命令行输入困难，且易出错问题。展开方式如下：
复杂类型 {"a":{"b": "c"}} 展开为 –a.b c。复杂类型数组使用.0，.1表示数组的第一个、第二个元素。基本类型数组不需要使用.0，.1，直接将数组多个元素用空格隔开依次输入，例如 –Integer 10 20，–String str1 str2。

执行以下命令，创建一台 CVM。

[root@VM_33_50_centos ~]# tccli cvm RunInstances –cli-unfold-argument –InstanceChargeType POSTPAID_BY_HOUR –InstanceChargePrepaid.Period 1 –InstanceChargePrepaid.RenewFlag DISABLE_NOTIFY_AND_MANUAL_RENEW –Placement.Zone ap-guangzhou-5 –InstanceType S1.SMALL1 –ImageId img-8toqc6s3 –SystemDisk.DiskType CLOUD_BASIC –SystemDisk.DiskSize 50 –InternetAccessible.InternetChargeType TRAFFIC_POSTPAID_BY_HOUR –InternetAccessible.InternetMaxBandwidthOut 10 –InternetAccessible.PublicIpAssigned True –InstanceCount 1 –InstanceName TCCLI-TEST –LoginSettings.Password isd@cloud –SecurityGroupIds sg-0rszg2vb –HostName TCCLI-HOST-NAME1

七、更多使用示例

你还可通过以下命令，进一步使用 TCCLI。

·执行 tccli help 命令，查看支持的产品，支持中文。

[root@VM_33_50_centos ~]# tccli helpUSAGE tccli [options] <service> [options] <action> [options] [options and parameters]OPTIONS help | show the tccli help info –version | show the version of tccliAVAILABLE SERVICES [cvm] [cbs] [cam] ……

·这篇以 CVM 为例，执行 tccli cvm help 命令，查看产品支持的接口。

[root@VM_33_50_centos ~]# tccli cvm helpNAME cvmAVAILABLE VERSIONS 2017-03-12 默认只展示最新版本信息，查看其它版本帮助信息加 –version xxxx-xx-xxDESCRIPTION cvm-2017-03-12 介绍如何使用API对云服务器进行操作，包括使用并管理实例、镜像、密钥等资源。USAGE tccli cvm <action> [–param…]OPTIONS help show the tccli cvm help infoAVAILABLE ACTIONS AllocateHosts 创建CDH实例 AssociateInstancesKeyPairs 绑定密钥对 AssociateSecurityGroups 绑定安全组 ……

·这篇以 CBS 的 DescribeDisks 接口为例，执行 tccli cbs DescribeDisks help 命令，查看接口支持的参数。

[root@VM_33_50_centos ~]# tccli cbs DescribeDisks helpNAME DescribeDisksDESCRIPTION cbs-2017-03-12-DescribeDisks 本接口（DescribeDisks）用于查询云硬盘列表。 * 可以根据云硬盘ID、云硬盘类型或者云硬盘状态等信息来查询云硬盘的详细信息，不同条件之间为与(AND)的关系，过滤信息详细请 见过滤器`Filter`。 * 如果参数为空，返回当前用户一定数量（`Limit`所指定的数量，默认为20）的云硬盘列表。USAGE tccli cbs DescribeDisks [–param…]OPTIONS help show the tccli cbs DescribeDisks help info –region identify the region to which the instance you want to work with belongs. –timeout specify a request timeout –secretKey specify a SecretKey …… AVAILABLE PARAMS –Limit (Integer | Optional) 返回数量，默认为20，最大值为100。关于`Limit`的更进一步介绍请参考 API [简介](/document/product/362/15633)中的相关小节。 –OrderField (String | Optional) 云盘列表排序的依据字段。取值范围：<br><li>CREATE_TIME：依据云盘的创建时间排序<br><li>DEADLINE：依据云盘的到期时间排序 <br>默认按云盘创建时间排序。 –Offset (Integer | Optional) 偏移量，默认为0。关于`Offset`的更进一步介绍请参考API[简介](/document/product/362/15633)中的相关小节。 ……

八、输出格式

输出格式支持 JSON、table 及 text 格式。

·JSON 格式：

[root@VM_33_50_centos ~]# tccli cvm DescribeRegions {"TotalCount": 20, "RegionSet": [ { "RegionState": "AVAILABLE", "Region": "ap-beijing", "RegionName": "华北地区(北京)" }, { "RegionState": "AVAILABLE", "Region": "ap-chengdu", "RegionName": "西南地区(成都)" }, { "RegionState": "AVAILABLE", "Region": "ap-guangzhou", "RegionName": "华南地区(广州)" }, { "RegionState": "AVAILABLE", "Region": "ap-hongkong", "RegionName": "港澳台地区(中国香港)" }, { "RegionState": "AVAILABLE", "Region": "ap-singapore", "RegionName": "东南亚地区(新加坡)" }, { "RegionState": "AVAILABLE", "Region": "ap-tokyo", "RegionName": "亚太地区(东京)" }, { "RegionState": "AVAILABLE", "Region": "eu-frankfurt", "RegionName": "欧洲地区(法兰克福)" }, ……], "RequestId": "e5125cf1-****-****-****-316f18eed021"}

·table 格式：

[root@VM_33_50_centos ~]# tccli cvm DescribeRegions –output table–| action |+—————————————+————–+| RequestId | TotalCount |+—————————————+————–+| 1af5f2a0-****-****-****-462f0271a69f | 20 |+—————————————+————–+|| RegionSet |||+——————-+—————-+—————+||| Region | RegionName | RegionState |||+——————-+—————-+—————+||| ap-bangkok | 亚太地区(曼谷) | AVAILABLE |||| ap-beijing | 华北地区(北京) | AVAILABLE |||| ap-chengdu | 西南地区(成都) | AVAILABLE |||| ap-chongqing | 西南地区(重庆) | AVAILABLE |||| ap-guangzhou | 华南地区(广州) | AVAILABLE |||| ap-guangzhou-open| 华南地区(广州Open) | AVAILABLE |||| ap-hongkong | 港澳台地区(中国香港) | AVAILABLE |||| ap-nanjing | 华东地区(南京) | AVAILABLE |||| ap-seoul | 亚太地区(首尔) | AVAILABLE |||| ap-shanghai | 华东地区(上海) | AVAILABLE |||| ap-shanghai-fsi | 华东地区(上海金融) | AVAILABLE |||| ap-shenzhen-fsi | 华南地区(深圳金融) | AVAILABLE |||| ap-singapore | 东南亚地区(新加坡) | AVAILABLE |||| ap-tokyo | 亚太地区(东京) | AVAILABLE |||| eu-frankfurt | 欧洲地区(法兰克福) | AVAILABLE |||| na-ashburn | 美国东部(弗吉尼亚) | AVAILABLE |||| na-siliconvalley | 美国西部(硅谷) | AVAILABLE |||+——————-+—————-+—————+|

·text 格式：

[root@VM_33_50_centos ~]# tccli cvm DescribeRegions –output text70bbd02f-****-****-****-afc5c34018ae 20REGIONSET ap-bangkok 亚太地区(曼谷) AVAILABLEREGIONSET ap-beijing 华北地区(北京) AVAILABLEREGIONSET ap-chengdu 西南地区(成都) AVAILABLEREGIONSET ap-chongqing 西南地区(重庆) AVAILABLEREGIONSET ap-guangzhou 华南地区(广州) AVAILABLEREGIONSET ap-guangzhou-open 华南地区(广州Open) AVAILABLEREGIONSET ap-hongkong 港澳台地区(中国香港) AVAILABLEREGIONSET ap-nanjing 华东地区(南京) AVAILABLEREGIONSET ap-seoul 亚太地区(首尔) AVAILABLEREGIONSET ap-shanghai 华东地区(上海) AVAILABLEREGIONSET ap-shanghai-fsi 华东地区(上海金融) AVAILABLEREGIONSET ap-shenzhen-fsi 华南地区(深圳金融) AVAILABLEREGIONSET ap-singapore 东南亚地区(新加坡) AVAILABLEREGIONSET ap-tokyo 亚太地区(东京) AVAILABLEREGIONSET eu-frankfurt 欧洲地区(法兰克福) AVAILABLEREGIONSET na-ashburn 美国东部(弗吉尼亚) AVAILABLEREGIONSET na-siliconvalley 美国西部(硅谷) AVAILABLE

九、高级功能

该步骤以 CVM 为例，详细介绍了如何使用 TCCLI 高级功能，包括多版本接口访问、指定最近的接入点、返回结果过滤、输出入参数据结构到 JSON 文件以及从 JSON 文件读取参数等。

十、多版本接口访问

某些产品可能存在多个版本的接口，TCCLI 默认访问最新版本的接口。如果你想访问特定旧版本的接口，可以通过以下方式实现：

·方式1：设置 CVM 产品默认使用版本为 2017-03-12。

tccli configure set cvm.version 2017-03-12

·方式2：在实时使用时指定版本号。

tccli cvm help –version 2017-03-12tccli cvm DescribeZones help –version 2017-03-12tccli cvm DescribeZones –version 2017-03-12

十一、指定最近的接入点（Endpoint）

TCCLI 默认会请求就近的接口点访问服务，你也可以针对某一产品指定自己的 Endpoint。

·设置 CVM 产品默认 Endpoint 为 ap-guangzhou。

tccli configure set cvm.endpoint cvm.ap-guangzhou.tencentcloudapi.com

·调用时实时指定：

tccli cvm DescribeZones –endpoint cvm.ap-guangzhou.tencentcloudapi.com

十二、返回结果过滤

·以 CVM DescribeZones 接口的返回为例，不加任何过滤时的输出。

[root@VM_180_248_centos ~]# tccli cvm DescribeZones { "TotalCount": 3, "ZoneSet": [ { "ZoneState": "AVAILABLE", "ZoneId": "100005", "Zone": "ap-guangzhou-5", "ZoneName": "广州五区" }, { "ZoneState": "AVAILABLE", "ZoneId": "100003", "Zone": "ap-guangzhou-3", "ZoneName": "广州三区" }, { "ZoneState": "AVAILABLE", "ZoneId": "100004", "Zone": "ap-guangzhou-4", "ZoneName": "广州四区" } ], "RequestId": "4fd313a6-****-****-****-898c02fcae02" }

·仅查看某个字段。

[root@VM_180_248_centos ~]# tccli cvm DescribeZones –filter TotalCount3

·指定某个数组类型对象的第 N 个子对象的信息。

[root@VM_180_248_centos ~]# tccli cvm DescribeZones –filter ZoneSet[0] { "ZoneState": "AVAILABLE", "ZoneId": "100005", "Zone": "ap-guangzhou-5", "ZoneName": "广州五区" }

·指定数组类型对象下所有某个名称的子对象的某个字段。

[root@VM_180_248_centos ~]# tccli cvm DescribeZones –filter ZoneSet[*].ZoneName [ "广州五区", "广州三区", "广州四区" ]

·过滤数组里的子对象，同时还以新的名称展示。

注意：需要将说明过滤行为的内容用单引号包裹起来。

[root@VM_180_248_centos ~]# tccli cvm DescribeZones –filter 'ZoneSet[*].{name:ZoneName, id:ZoneId}' [ { "name": "广州五区", "id": "100005" }, { "name": "广州三区", "id": "100003" }, { "name": "广州四区", "id": "100004" } ]

十三、结果轮询

在使用产品的过程中，有些操作并不能即时完成，你可以使用结果轮询功能来不断查询操作是否完成。例如，在开启一台实例后，实例并不能立即进入 RUNNING 状态，则可使用结果轮询功能对实例状态轮询，直到出现 RUNNING 状态为止。

·执行以下命令，程序将按照一定时间间隔对实例的状态进行轮询，直到实例的状态为 RUNNING 或者超时为止。

tccli cvm DescribeInstancesStatus –region ap-hongkong –waiter "{'expr':'InstanceStatusSet[0].InstanceState','to':'RUNNING'}"

·你可自定义超时时间和睡眠时间，执行以下命令，设定超时时间为180秒，睡眠时间为5秒。

tccli cvm DescribeInstancesStatus –region ap-hongkong –waiter "{'expr':'InstanceStatusSet[0].InstanceState','to':'RUNNING','timeout':180,'interval':5}"

·你可在配置文件中设置可选子参数的值。在 default.configure 文件中添加如下参数，设置系统超时时间为180s，睡眠时间为5s。

"waiter": { "interval": 5, "timeout": 180 },

参数说明如下：

·–region：需替换为你实例所在的地域。

·–waiter：后的参数需使用双引号包裹，且参数需为 JSON 格式。其中必选及可选参数如下表：

十四、如何购买命令行工具？

本服务免费。当你遇到问题时，请 联系我们 寻求相应的帮助。

十五、如何实现接口鉴权？

在 API 支持的每个产品文档目录下，可选择调用方法 > 接口鉴权，结合产品的接口鉴权文档进行实现。例如，可前往 CVM 接口鉴权 进行查看。