黑石物理服务器1.0 签名方法 - API 文档

签名方法 v1 简单易用，但是功能和安全性都不如签名方法 v3，推荐使用签名方法 v3。

首次接触，建议使用 API Explorer 中的“签名串生成”功能，选择签名版本为“API 3.0 签名 v1”，可以生成签名过程进行验证，并提供了部分编程语言的签名示例，也可直接生成 SDK 代码。推荐使用腾讯云 API 配套的 7 种常见的编程语言 SDK，已经封装了签名和请求过程，均已开源，支持 Python、Java、PHP、Go、NodeJS、.NET、C++。

腾讯云 API 会对每个访问请求进行身份验证，即每个请求都需要在公共请求参数中包含签名信息（Signature）以验证请求者身份。
签名信息由安全凭证生成，安全凭证包括 SecretId 和 SecretKey；若用户还没有安全凭证，请前往 云API密钥页面 申请，否则无法调用云 API 接口。

1. 申请安全凭证

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

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

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

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

注意：每个账号最多可以拥有两对 SecretId/SecretKey。

2. 生成签名串

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

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

• SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******
• SecretKey: Gu5t9xGARNpq86cd98joQYCN3*******

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

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

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' : 'AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******',
  '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=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******&Timestamp=1465185768&Version=2017-03-12

2.3. 拼接签名原文字符串

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

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

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

示例的拼接结果为：

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

2.4. 生成签名串

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

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

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

最终得到的签名串为：

zmmjn35mikh6pM3V7sUEuX4wyYM=

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

3. 签名串编码

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

如上一步生成的签名串为 zmmjn35mikh6pM3V7sUEuX4wyYM= ，最终得到的签名串请求参数（Signature）为：zmmjn35mikh6pM3V7sUEuX4wyYM%3D，它将用于生成最终的请求 URL。

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

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

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

4. 签名失败

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

5. 签名演示

在实际调用 API 3.0 时，推荐使用配套的腾讯云 SDK 3.0 ，SDK 封装了签名的过程，开发时只关注产品提供的具体接口即可。详细信息参见 SDK 中心。当前支持的编程语言有：

• Python
• Java
• PHP
• Go
• NodeJS
• .NET
• C++

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

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

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

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

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

Java

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进行urlencode
          url.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", "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"); // 公共参数
      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), "Gu5t9xGARNpq86cd98joQYCN3*******", "HmacSHA1")); // 公共参数
      System.out.println(getUrl(params));
  }
}

Python

注意：如果是在 Python 2 环境中运行，需要先安装 requests 依赖包： pip install requests 。

# -*- coding: utf8 -*-
import base64
import hashlib
import hmac
import time
import requests
secret_id = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secret_key = "Gu5t9xGARNpq86cd98joQYCN3*******"
def get_string_to_sign(method, endpoint, params):
  s = method + endpoint + "/?"
  query_str = "&".join("%s=%s" % (k, params[k]) for k in sorted(params))
  return s + query_str
def sign_str(key, s, method):
  hmac_str = hmac.new(key.encode("utf8"), s.encode("utf8"), method).digest()
  return base64.b64encode(hmac_str)
if __name__ == '__main__':
  endpoint = "cvm.tencentcloudapi.com"
  data = {
      'Action' : 'DescribeInstances',
      'InstanceIds.0' : 'ins-09dx96dg',
      'Limit' : 20,
      'Nonce' : 11886,
      'Offset' : 0,
      'Region' : 'ap-guangzhou',
      'SecretId' : secret_id,
      'Timestamp' : 1465185768, # int(time.time())
      'Version': '2017-03-12'
  }
  s = get_string_to_sign("GET", endpoint, data)
  data["Signature"] = sign_str(secret_key, s, hashlib.sha1)
  print(data["Signature"])
  # 此处会实际调用，成功后可能产生计费
  # resp = requests.get("https://" + endpoint, params=data)
  # print(resp.url)

Golang

package main
import (
  "bytes"
  "crypto/hmac"
  "crypto/sha1"
  "encoding/base64"
  "fmt"
  "sort"
  "strconv"
)
func main() {
  secretId := "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
  secretKey := "Gu5t9xGARNpq86cd98joQYCN3*******"
  params := map[string]string{
      "Nonce":         "11886",
      "Timestamp":     strconv.Itoa(1465185768),
      "Region":        "ap-guangzhou",
      "SecretId":      secretId,
      "Version":       "2017-03-12",
      "Action":        "DescribeInstances",
      "InstanceIds.0": "ins-09dx96dg",
      "Limit":         strconv.Itoa(20),
      "Offset":        strconv.Itoa(0),
  }
   var buf bytes.Buffer
  buf.WriteString("GET")
  buf.WriteString("cvm.tencentcloudapi.com")
  buf.WriteString("/")
  buf.WriteString("?")
   // sort keys by ascii asc order
  keys := make([]string, 0, len(params))
  for k, _ := range params {
      keys = append(keys, k)
  }
  sort.Strings(keys)
   for i := range keys {
      k := keys[i]
      buf.WriteString(k)
      buf.WriteString("=")
      buf.WriteString(params[k])
      buf.WriteString("&")
  }
  buf.Truncate(buf.Len() - 1)
   hashed := hmac.New(sha1.New, []byte(secretKey))
  hashed.Write(buf.Bytes())
   fmt.Println(base64.StdEncoding.EncodeToString(hashed.Sum(nil)))
}

PHP

<?php
$secretId = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
$secretKey = "Gu5t9xGARNpq86cd98joQYCN3*******";
$param["Nonce"] = 11886;//rand();
$param["Timestamp"] = 1465185768;//time();
$param["Region"] = "ap-guangzhou";
$param["SecretId"] = $secretId;
$param["Version"] = "2017-03-12";
$param["Action"] = "DescribeInstances";
$param["InstanceIds.0"] = "ins-09dx96dg";
$param["Limit"] = 20;
$param["Offset"] = 0;
ksort($param);
$signStr = "GETcvm.tencentcloudapi.com/?";
foreach ( $param as $key => $value ) {
  $signStr = $signStr . $key . "=" . $value . "&";
}
$signStr = substr($signStr, 0, -1);
$signature = base64_encode(hash_hmac("sha1", $signStr, $secretKey, true));
echo $signature.PHP_EOL;
// need to install and enable curl extension in php.ini
// $param["Signature"] = $signature;
// $url = "https://cvm.tencentcloudapi.com/?".http_build_query($param);
// echo $url.PHP_EOL;
// $ch = curl_init();
// curl_setopt($ch, CURLOPT_URL, $url);
// $output = curl_exec($ch);
// curl_close($ch);
// echo json_decode($output);

Ruby

# -*- coding: UTF-8 -*-
# require ruby>=2.3.0
require 'time'
require 'openssl'
require 'base64'
secret_id = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secret_key = "Gu5t9xGARNpq86cd98joQYCN3*******"
method = 'GET'
endpoint = 'cvm.tencentcloudapi.com'
data = {
'Action' => 'DescribeInstances',
'InstanceIds.0' => 'ins-09dx96dg',
'Limit' => 20,
'Nonce' => 11886,
'Offset' => 0,
'Region' => 'ap-guangzhou',
'SecretId' => secret_id,
'Timestamp' => 1465185768, # Time.now.to_i
'Version' => '2017-03-12',
}
sign = method + endpoint + '/?'
params = []
data.sort.each do |item|
params << "#{item[0]}=#{item[1]}"
end
sign += params.join('&')
digest = OpenSSL::Digest.new('sha1')
data['Signature'] = Base64.encode64(OpenSSL::HMAC.digest(digest, secret_key, sign))
puts data['Signature']
# require 'net/http'
# uri = URI('https://' + endpoint)
# uri.query = URI.encode_www_form(data)
# p uri
# res = Net::HTTP.get_response(uri)
# puts res.body

DotNet

using System;
using System.Collections.Generic;
using System.Net;
using System.Security.Cryptography;
using System.Text;
public class Application {
  public static string Sign(string signKey, string secret)
  {
      string signRet = string.Empty;
          using (HMACSHA1 mac = new HMACSHA1(Encoding.UTF8.GetBytes(signKey)))
          {
              byte[] hash = mac.ComputeHash(Encoding.UTF8.GetBytes(secret));
              signRet = Convert.ToBase64String(hash);
          }
      return signRet;
  }
  public static string MakeSignPlainText(SortedDictionary<string, string> requestParams, string requestMethod, string requestHost, string requestPath)
  {
      string retStr = "";
      retStr += requestMethod;
      retStr += requestHost;
      retStr += requestPath;
      retStr += "?";
      string v = "";
      foreach (string key in requestParams.Keys)
      {
          v += string.Format("{0}={1}&", key, requestParams[key]);
      }
      retStr += v.TrimEnd('&');
      return retStr;
  }
   public static void Main(string[] args)
  {
      // 密钥参数
      string SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
      string SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******";
       string endpoint = "cvm.tencentcloudapi.com";
      string region = "ap-guangzhou";
      string action = "DescribeInstances";
      string version = "2017-03-12";
      double RequestTimestamp = 1465185768;  // 时间戳 2019-02-26 00:44:25,此参数作为示例，以实际为准
      // long timestamp = ToTimestamp() / 1000;
      // string requestTimestamp = timestamp.ToString();
      Dictionary<string, string> param = new Dictionary<string, string>();
      param.Add("Limit", "20");
      param.Add("Offset", "0");
      param.Add("InstanceIds.0", "ins-09dx96dg");
      param.Add("Action", action);
      param.Add("Nonce", "11886");
      // param.Add("Nonce", Math.Abs(new Random().Next()).ToString());
       param.Add("Timestamp", RequestTimestamp.ToString());
      param.Add("Version", version);
       param.Add("SecretId", SECRET_ID);
      param.Add("Region", region);
      SortedDictionary<string, string> headers = new SortedDictionary<string, string>(param, StringComparer.Ordinal);
      string sigInParam = MakeSignPlainText(headers, "GET", endpoint, "/");
      string sigOutParam = Sign(SECRET_KEY, sigInParam);
      Console.WriteLine(sigOutParam);
  }
}

NodeJS

const crypto = require('crypto');
function get_req_url(params, endpoint){
  params['Signature'] = escape(params['Signature']);
  const url_strParam = sort_params(params)
  return "https://" + endpoint + "/?" + url_strParam.slice(1);
}
function formatSignString(reqMethod, endpoint, path, strParam){
  let strSign = reqMethod + endpoint + path + "?" + strParam.slice(1);
  return strSign;
}
function sha1(secretKey, strsign){
  let signMethodMap = {'HmacSHA1': "sha1"};
  let hmac = crypto.createHmac(signMethodMap['HmacSHA1'], secretKey || "");
  return hmac.update(Buffer.from(strsign, 'utf8')).digest('base64')
}
function sort_params(params){
  let strParam = "";
  let keys = Object.keys(params);
  keys.sort();
  for (let k in keys) {
      //k = k.replace(/_/g, '.');
      strParam += ("&" + keys[k] + "=" + params[keys[k]]);
  }
  return strParam
}
function main(){
  // 密钥参数
  const SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
  const SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******"
   const endpoint = "cvm.tencentcloudapi.com"
  const Region = "ap-guangzhou"
  const Version = "2017-03-12"
  const Action = "DescribeInstances"
  const Timestamp = 1465185768  // 时间戳 2016-06-06 12:02:48, 此参数作为示例，以实际为准
  // const Timestamp = Math.round(Date.now() / 1000)
  const Nonce = 11886  // 随机正整数
  //const nonce = Math.round(Math.random() * 65535)
   let params = {};
  params['Action'] = Action;
  params['InstanceIds.0'] = 'ins-09dx96dg';
  params['Limit'] = 20;
  params['Offset'] = 0;
  params['Nonce'] = Nonce;
  params['Region'] = Region;
  params['SecretId'] = SECRET_ID;
  params['Timestamp'] = Timestamp;
  params['Version'] = Version;
   // 1. 对参数排序,并拼接请求字符串
  strParam = sort_params(params)
   // 2. 拼接签名原文字符串
  const reqMethod = "GET";
  const path = "/";
  strSign = formatSignString(reqMethod, endpoint, path, strParam)
  // console.log(strSign)
   // 3. 生成签名串
  params['Signature'] = sha1(SECRET_KEY, strSign)
  console.log(params['Signature'])
   // 4. 进行url编码并拼接请求url
  // const req_url = get_req_url(params, endpoint)
  // console.log(params['Signature'])
  // console.log(req_url)
}
main()