常用公有云接入—

一、ES术语表

本文档涉及的一些常用术语如下：

术语	全称	中文	说明
Instance	Instance	实例	指代一台云服务器。
Region	Region	地域	表示资源所在的地域，每个地域包含一个或多个可用区。
Zone	Zone	可用区	指腾讯云在同一地域内电力和网络互相独立的物理数据中心。目标是能够保证可用区之间故障相互隔离，不出现故障扩散，使得用户的业务持续在线服务。
Image	Image	镜像	CVM实例上软件环境的拷贝，一般包括操作系统和已安装的软件；我们使用镜像来创建实例。
SecurityGroup	Security Group	安全组	一种有状态的包过滤功能的虚拟防火墙，用于控制CVM实例的网络访问，是一种重要的网络安全隔离手段。
EIP	Elastic IP	弹性IP	弹性IP是公网IP的一种。与普通公网IP不同的是，弹性IP归属于用户账户而不是实例；实例与公网IP的映射关系随时可以更改。
无	无	包年包月	一种计费模式，参看计费模式说明。
无	无	按量计费	一种计费模式，参看计费模式说明。

输入参数与返回参数释义

Limit 和 Offset

用来控制分页的参数；Limit 为单次返回的最多条目数量，Offset 为偏移量。当相应结果是列表形式时，如果数量超过了 Limit 所限定的值，那么只返回 Limit 个值。

举例来说，参数 Offset=0&Limit=20 返回第 0 到 20 项，Offset=20&Limit=20 返回第 20 到 40 项，Offset=40&Limit=20 返回第 40 到 60 项；以此类推。
Ids.N

同时输入多个参数的格式。当遇到形如这样的格式时，那么该输入参数可以同时传多个。例如：

GET 请求或者 POST x-www-form-urlencoded 请求：Ids.0=ins-r8hr2upy&Ids.1=ins-5d8a23rs&Ids.2=ins--dcs9x3gz

以此类推（以下标 0 开始）。

POST json 请求：{"Ids": ["ins-r8hr2upy", "ins-5d8a23rs", "ins--dcs9x3gz"]}

二、接口鉴权

1. 申请安全凭证

在第一次使用云API之前，请前往云API密钥页面申请安全凭证。安全凭证包括 SecretId 和 SecretKey：

SecretId 用于标识 API 调用者身份
SecretKey 用于加密签名字符串和服务器端验证签名字符串的密钥。
用户必须严格保管安全凭证，避免泄露。

申请安全凭证的具体步骤如下：

登录腾讯云管理中心控制台。
前往云API密钥的控制台页面
在云API密钥页面，点击【新建】即可以创建一对SecretId/SecretKey

注意：开发商帐号最多可以拥有两对 SecretId / SecretKey。

2. 生成签名串

有了安全凭证SecretId 和 SecretKey后，就可以生成签名串了。以下是生成签名串的详细过程：

假设用户的 SecretId 和 SecretKey 分别是：

SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE
SecretKey: Gu5t9xGARNpq86cd98joQYCN3EXAMPLE

注意：这里只是示例，请根据用户实际申请的 SecretId 和 SecretKey 进行后续操作！

以云服务器查看实例列表(DescribeInstances)请求为例，当用户调用这一接口时，其请求参数可能如下:

参数名称	中文	参数值
Action	方法名	DescribeInstances
SecretId	密钥Id	AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE
Timestamp	当前时间戳	1465185768
Nonce	随机正整数	11886
Region	实例所在区域	ap-guangzhou
InstanceIds.0	待查询的实例ID	ins-09dx96dg
Offset	偏移量	0
Limit	最大允许输出	20
Version	接口版本号	2017-03-12

2.1. 对参数排序

首先对所有请求参数按参数名的字典序（ ASCII 码）升序排序。注意：1）只按参数名进行排序，参数值保持对应即可，不参与比大小；2）按 ASCII 码比大小，如 InstanceIds.2 要排在 InstanceIds.12 后面，不是按字母表，也不是按数值。用户可以借助编程语言中的相关排序函数来实现这一功能，如 php 中的 ksort 函数。上述示例参数的排序结果如下:

{'Action' : 'DescribeInstances','InstanceIds.0' : 'ins-09dx96dg','Limit' : 20,'Nonce' : 11886,'Offset' : 0,'Region' : 'ap-guangzhou','SecretId' : 'AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE','Timestamp' : 1465185768,'Version': '2017-03-12',
}

使用其它程序设计语言开发时，可对上面示例中的参数进行排序，得到的结果一致即可。

2.2. 拼接请求字符串

此步骤生成请求字符串。将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式，如对 Action 参数，其参数名称为 "Action" ，参数值为 "DescribeInstances" ，因此格式化后就为 Action=DescribeInstances 。 注意：“参数值”为原始值而非url编码后的值。

然后将格式化后的各个参数用"&"拼接在一起，最终生成的请求字符串为:

Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

2.3. 拼接签名原文字符串

此步骤生成签名原文字符串。签名原文字符串由以下几个参数构成:

请求方法: 支持 POST 和 GET 方式，这里使用 GET 请求，注意方法为全大写。
请求主机:查看实例列表(DescribeInstances)的请求域名为：cvm.tencentcloudapi.com。实际的请求域名根据接口所属模块的不同而不同，详见各接口说明。
请求路径: 当前版本云API的请求路径固定为 / 。
请求字符串: 即上一步生成的请求字符串。

签名原文串的拼接规则为: 请求方法 + 请求主机 +请求路径 + ? + 请求字符串

示例的拼接结果为：

GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

2.4. 生成签名串

此步骤生成签名串。首先使用 HMAC-SHA1 算法对上一步中获得的签名原文字符串进行签名，然后将生成的签名串使用 Base64 进行编码，即可获得最终的签名串。

具体代码如下，以 PHP 语言为例:

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3EXAMPLE';
$srcStr = 'GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12';
$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
echo $signStr;

最终得到的签名串为:

EliP9YW3pW28FpsEdkXt/+WcGeI=

使用其它程序设计语言开发时，可用上面示例中的原文进行签名验证，得到的签名串与例子中的一致即可。

3. 签名串编码

生成的签名串并不能直接作为请求参数，需要对其进行 URL 编码。

如上一步生成的签名串为 EliP9YW3pW28FpsEdkXt/+WcGeI= ，最终得到的签名串请求参数（Signature）为：EliP9YW3pW28FpsEdkXt%2f%2bWcGeI%3d，它将用于生成最终的请求 URL。

注意：如果用户的请求方法是 GET，或者请求方法为 POST 同时 Content-Type 为 application/x-www-form-urlencoded，则发送请求时所有请求参数的值均需要做 URL 编码，参数键和=符号不需要编码。非 ASCII 字符在 URL 编码前需要先以 UTF-8 进行编码。

注意：有些编程语言的 http 库会自动为所有参数进行 urlencode，在这种情况下，就不需要对签名串进行 URL 编码了，否则两次 URL 编码会导致签名失败。

注意：其他参数值也需要进行编码，编码采用 RFC 3986。使用 %XY 对特殊字符例如汉字进行百分比编码，其中“X”和“Y”为十六进制字符（0-9 和大写字母 A-F），使用小写将引发错误。

4. 签名失败

根据实际情况，存在以下签名失败的错误码，请根据实际情况处理

错误代码	错误描述
AuthFailure.SignatureExpire	签名过期
AuthFailure.SecretIdNotFound	密钥不存在
AuthFailure.SignatureFailure	签名错误
AuthFailure.TokenFailure	token 错误
AuthFailure.InvalidSecretId	密钥非法（不是云 API 密钥类型）

5. 签名演示

在实际调用 API 3.0 时，推荐使用配套的腾讯云 SDK 3.0 ，SDK 封装了签名的过程，开发时只关注产品提供的具体接口即可。

为了更清楚的解释签名过程，下面以实际编程语言为例，将上述的签名过程具体实现。请求的域名、调用的接口和参数的取值都以上述签名过程为准，代码只为解释签名过程，并不具备通用性，实际开发请尽量使用 SDK 。

最终输出的 url 可能为：https://cvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE&Signature=EliP9YW3pW28FpsEdkXt%2F%2BWcGeI%3D&Timestamp=1465185768&Version=2017-03-12

注意：由于示例中的密钥是虚构的，时间戳也不是系统当前时间，因此如果将此 url 在浏览器中打开或者用 curl 等命令调用时会返回鉴权错误：签名过期。为了得到一个可以正常返回的 url ，需要修改示例中的 SecretId 和 SecretKey 为真实的密钥，并使用系统当前时间戳作为 Timestamp 。

注意：在下面的示例中，不同编程语言，甚至同一语言每次执行得到的 url 可能都有所不同，表现为参数的顺序不同，但这并不影响正确性。只要所有参数都在，且签名计算正确即可。

注意：以下代码仅适用于 API 3.0，不能直接用于其他的签名流程，即使是旧版的 API ，由于存在细节差异也会导致签名计算错误，请以对应的实际文档为准。

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Random;
import java.util.TreeMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;public class TencentCloudAPIDemo {private final static String CHARSET = "UTF-8";public static String sign(String s, String key, String method) throws Exception {Mac mac = Mac.getInstance(method);SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(CHARSET), mac.getAlgorithm());mac.init(secretKeySpec);byte[] hash = mac.doFinal(s.getBytes(CHARSET));return DatatypeConverter.printBase64Binary(hash);}public static String getStringToSign(TreeMap<String, Object> params) {StringBuilder s2s = new StringBuilder("GETcvm.tencentcloudapi.com/?");// 签名时要求对参数进行字典排序，此处用TreeMap保证顺序for (String k : params.keySet()) {s2s.append(k).append("=").append(params.get(k).toString()).append("&");}return s2s.toString().substring(0, s2s.length() - 1);}public static String getUrl(TreeMap<String, Object> params) throws UnsupportedEncodingException {StringBuilder url = new StringBuilder("https://cvm.tencentcloudapi.com/?");// 实际请求的url中对参数顺序没有要求for (String k : params.keySet()) {// 需要对请求串进行urlencode，由于key都是英文字母，故此处仅对其value进行urlencodeurl.append(k).append("=").append(URLEncoder.encode(params.get(k).toString(), CHARSET)).append("&");}return url.toString().substring(0, url.length() - 1);}public static void main(String[] args) throws Exception {TreeMap<String, Object> params = new TreeMap<String, Object>(); // TreeMap可以自动排序// 实际调用时应当使用随机数，例如：params.put("Nonce", new Random().nextInt(java.lang.Integer.MAX_VALUE));params.put("Nonce", 11886); // 公共参数// 实际调用时应当使用系统当前时间，例如：   params.put("Timestamp", System.currentTimeMillis() / 1000);params.put("Timestamp", 1465185768); // 公共参数params.put("SecretId", "AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE"); // 公共参数params.put("Action", "DescribeInstances"); // 公共参数params.put("Version", "2017-03-12"); // 公共参数params.put("Region", "ap-guangzhou"); // 公共参数params.put("Limit", 20); // 业务参数params.put("Offset", 0); // 业务参数params.put("InstanceIds.0", "ins-09dx96dg"); // 业务参数params.put("Signature", sign(getStringToSign(params), "Gu5t9xGARNpq86cd98joQYCN3EXAMPLE", "HmacSHA1")); // 公共参数System.out.println(getUrl(params));}
}

三、腾讯SDK

GITHUT地址

package com.tencentcloudapi.es.v20180416;import java.lang.reflect.Type;
import com.google.gson.JsonSyntaxException;
import com.google.gson.reflect.TypeToken;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
import com.tencentcloudapi.common.AbstractClient;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.JsonResponseModel;
import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.es.v20180416.models.*;public class EsClient extends AbstractClient{private static String endpoint = "es.tencentcloudapi.com";private static String version = "2018-04-16";/*** 构造client* @param credential 认证信息实例* @param region 产品地域*/public EsClient(Credential credential, String region) {this(credential, region, new ClientProfile());}/*** 构造client* @param credential 认证信息实例* @param region    产品地域* @param profile 配置实例*/public EsClient(Credential credential, String region, ClientProfile profile) {super(EsClient.endpoint, EsClient.version, credential, region, profile);}/***创建指定规格的ES集群实例* @param req CreateInstanceRequest* @return CreateInstanceResponse* @throws TencentCloudSDKException*/public CreateInstanceResponse CreateInstance(CreateInstanceRequest req) throws TencentCloudSDKException{JsonResponseModel<CreateInstanceResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<CreateInstanceResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "CreateInstance"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***销毁集群实例 * @param req DeleteInstanceRequest* @return DeleteInstanceResponse* @throws TencentCloudSDKException*/public DeleteInstanceResponse DeleteInstance(DeleteInstanceRequest req) throws TencentCloudSDKException{JsonResponseModel<DeleteInstanceResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<DeleteInstanceResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "DeleteInstance"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***查询用户该地域下符合条件的ES集群的日志* @param req DescribeInstanceLogsRequest* @return DescribeInstanceLogsResponse* @throws TencentCloudSDKException*/public DescribeInstanceLogsResponse DescribeInstanceLogs(DescribeInstanceLogsRequest req) throws TencentCloudSDKException{JsonResponseModel<DescribeInstanceLogsResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<DescribeInstanceLogsResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "DescribeInstanceLogs"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***查询实例指定条件下的操作记录* @param req DescribeInstanceOperationsRequest* @return DescribeInstanceOperationsResponse* @throws TencentCloudSDKException*/public DescribeInstanceOperationsResponse DescribeInstanceOperations(DescribeInstanceOperationsRequest req) throws TencentCloudSDKException{JsonResponseModel<DescribeInstanceOperationsResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<DescribeInstanceOperationsResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "DescribeInstanceOperations"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***查询用户该地域下符合条件的所有实例* @param req DescribeInstancesRequest* @return DescribeInstancesResponse* @throws TencentCloudSDKException*/public DescribeInstancesResponse DescribeInstances(DescribeInstancesRequest req) throws TencentCloudSDKException{JsonResponseModel<DescribeInstancesResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<DescribeInstancesResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "DescribeInstances"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***重启ES集群实例(用于系统版本更新等操作) * @param req RestartInstanceRequest* @return RestartInstanceResponse* @throws TencentCloudSDKException*/public RestartInstanceResponse RestartInstance(RestartInstanceRequest req) throws TencentCloudSDKException{JsonResponseModel<RestartInstanceResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<RestartInstanceResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "RestartInstance"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}/***对集群进行扩缩容，修改实例名称，修改配置，重置密码， 添加Kibana黑白名单等操作。参数中InstanceId为必传参数，ForceRestart为选填参数，剩余参数传递组合及含义如下：<br>InstanceName：修改实例名称(仅用于标识实例)<br>NodeNum：集群数据节点横向扩缩容<br>NodeType, DiskSize：集群数据节点纵向扩缩容<br>MasterNodeNum: 集群专用主节点横向扩缩容<br>MasterNodeType, MasterNodeDiskSize: 集群专用主节点纵向扩缩容<br>EsConfig：修改集群配置<br>Password：修改集群密码<br>EsAcl：修改Kibana密码<br>CosBackUp: 设置集群COS自动备份信息<br>
以上参数组合只能传递一种，多传或少传均会导致请求失败<br>* @param req UpdateInstanceRequest* @return UpdateInstanceResponse* @throws TencentCloudSDKException*/public UpdateInstanceResponse UpdateInstance(UpdateInstanceRequest req) throws TencentCloudSDKException{JsonResponseModel<UpdateInstanceResponse> rsp = null;try {Type type = new TypeToken<JsonResponseModel<UpdateInstanceResponse>>() {}.getType();rsp  = gson.fromJson(this.internalRequest(req, "UpdateInstance"), type);} catch (JsonSyntaxException e) {throw new TencentCloudSDKException(e.getMessage());}return rsp.response;}}

四、RESTful API

API 概览

调用方式

请求结构
公共参数
接口鉴权 v3
接口鉴权
返回结果

实例相关接口

创建实例
创建实例询价
启动实例
关闭实例
重启实例
重装实例
重装实例询价
重置实例密码
退还实例
查看实例列表
查看实例状态列表
修改实例的属性
修改实例所属项目
调整实例配置
调整实例配置询价
扩容实例磁盘
扩容实例磁盘询价
查询所支持的实例机型族信息
查询实例机型列表
续费实例
续费实例询价
修改实例续费标识
查询实例带宽配置
查询网络计费类型
调整实例带宽上限
调整实例带宽上限询价
获取可用区机型配置信息
创建分散置放群组
删除分散置放群组
查询置放群组配额
查询分散置放群组信息
修改分散置放群组属性
绑定安全组
查询实例管理终端地址
查询实例操作限制
解绑安全组
修改实例计费模式询价
修改实例计费模式
修改实例vpc属性