一、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屬性

總結

以上是生活随笔為你收集整理的常用公有云接入——腾讯的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。