cvm.tencentcloudapi.com),也支持指定地域域名访问(例如:广州地域的域名为 cvm.ap-guangzhou.tencentcloudapi.com),各地域参数见下文公共参数中的地域列表,详情请参见各产品的“请求结构”文档说明判断是否支持该地域。参数名称 | 类型 | 必选 | 描述 |
X-TC-Action | String | 是 | 操作的接口名称。取值参考接口文档中输入参数公共参数 Action 的说明。例如云服务器的查询实例列表接口,取值为 DescribeInstances。 |
X-TC-Region | String | - | 地域参数,用来标识希望操作哪个地域的数据。接口接受的地域取值参考接口文档中输入参数公共参数 Region 的说明。注意:某些接口不需要传递该参数,接口文档中会对此特别说明,此时即使传递该参数也不会生效。 |
X-TC-Timestamp | Integer | 是 | 当前 UNIX 时间戳,可记录发起 API 请求的时间。例如1529223702。注意:如果与服务器时间相差超过5分钟,会引起签名过期错误。 |
X-TC-Version | String | 是 | 操作的 API 的版本。取值参考接口文档中入参公共参数 Version 的说明。例如云服务器的版本2017-03-12。 |
Authorization | String | 是 | HTTP 标准身份认证头部字段,例如: TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168 其中: TC3-HMAC-SHA256:签名方法,目前固定取该值。 Credential:签名凭证,AKIDEXAMPLE 是 SecretId。 Date 是 UTC 标准时间的日期,取值需要和公共参数 X-TC-Timestamp 换算的 UTC 标准时间日期一致。 service 为产品名,通常为域名前缀,例如域名 cvm.tencentcloudapi.com 意味着产品名是 cvm。本产品取值为 cvm。 SignedHeaders:参与签名计算的头部信息,content-type 和 host 为必选头部。 Signature:签名摘要,计算过程详见下文。 |
X-TC-Token | String | 否 | 临时证书所用的 Token ,需要结合临时密钥一起使用。临时密钥和 Token 需要到访问管理服务调用接口获取。长期密钥不需要 Token。 |
AKIDz8krbsJ5**********mLPx3EXAMPLE 和 Gu5t9xGAR***********EXAMPLE。用户想查看广州区云服务器名为 “未命名” 的主机状态,只返回一条数据。则请求可能为: curl -X POST https://cvm.tencentcloudapi.com \\-H "Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea809ad7a8c8f7a4507b9bddcbaa8e581f516e8da2f66e2c5a96525168" \\-H "Content-Type: application/json; charset=utf-8" \\-H "Host: cvm.tencentcloudapi.com" \\-H "X-TC-Action: DescribeInstances" \\-H "X-TC-Timestamp: 1551113065" \\-H "X-TC-Version: 2017-03-12" \\-H "X-TC-Region: ap-guangzhou" \\-d '{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}'

CanonicalRequest =HTTPRequestMethod + '\\n' +CanonicalURI + '\\n' +CanonicalQueryString + '\\n' +CanonicalHeaders + '\\n' +SignedHeaders + '\\n' +HashedRequestPayload
字段名称 | 解释 |
HTTPRequestMethod | HTTP 请求方法(GET、POST)。此示例取值为 POST。 |
CanonicalURI | URI 参数,API 3.0 固定为正斜杠(/)。 |
CanonicalQueryString | 发起 HTTP 请求 URL 中的查询字符串,对于 POST 请求,固定为空字符串"",对于 GET 请求,则为 URL 中问号(?)后面的字符串内容,例如:Limit=10&Offset=0。 注意:CanonicalQueryString 需要参考 RFC3986 进行 URLEncode,字符集 UTF8,推荐使用编程语言标准库,所有特殊字符均需编码,大写形式。 |
CanonicalHeaders | 参与签名的头部信息,至少包含 host 和 content-type 两个头部,也可加入自定义的头部参与签名以提高自身请求的唯一性和安全性。 拼接规则:头部 key 和 value 统一转成小写,并去掉首尾空格,按照 key:value\\n 格式拼接;多个头部,按照头部 key(小写)的 ASCII 升序进行拼接。此示例计算结果是 content-type:application/json; charset=utf-8\\nhost:cvm.tencentcloudapi.com\\n。 注意:content-type 必须和实际发送的相符合,有些编程语言网络库即使未指定也会自动添加 charset 值,如果签名时和发送时不一致,服务器会返回签名校验失败。 |
SignedHeaders | 参与签名的头部信息,说明此次请求有哪些头部参与了签名,和 CanonicalHeaders 包含的头部内容是一一对应的。content-type 和 host 为必选头部。 拼接规则:头部 key 统一转成小写;多个头部 key(小写)按照 ASCII 升序进行拼接,并且以分号(;)分隔。此示例为 content-type;host |
HashedRequestPayload | 请求正文(Requestpayload,即 body,此示例为 {"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]})的哈希值,计算伪代码为 Lowercase(HexEncode(Hash.SHA256(RequestPayload))),即对 HTTP 请求正文做 SHA256 哈希,然后十六进制编码,最后编码串转换成小写字母。对于 GET 请求,RequestPayload 固定为空字符串。此示例计算结果是 35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064。 |
POST/content-type:application/json; charset=utf-8host:cvm.tencentcloudapi.comcontent-type;host35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064
StringToSign =Algorithm + \\n +RequestTimestamp + \\n +CredentialScope + \\n +HashedCanonicalRequest
字段名称 | 解释 |
Algorithm | 签名算法,目前固定为 TC3-HMAC-SHA256。 |
RequestTimestamp | 请求时间戳,即请求头部的公共参数 X-TC-Timestamp 取值,取当前时间 UNIX 时间戳,精确到秒。此示例取值为 1551113065。 |
CredentialScope | 凭证范围,格式为 Date/service/tc3_request,包含日期、所请求的服务和终止字符串(tc3_request)。Date 为 UTC 标准时间的日期,取值需要和公共参数 X-TC-Timestamp 换算的 UTC 标准时间日期一致;service 为产品名,必须与调用的产品域名一致。此示例计算结果是2019-02-25/cvm/tc3_request。 |
HashedCanonicalRequest | 前述步骤拼接所得规范请求串的哈希值,计算伪代码为 Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))。此示例计算结果是 5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031。 |
TC3-HMAC-SHA25615511130652019-02-25/cvm/tc3_request5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031
#include <tencentcloud/core/Sign.h>#include <tencentcloud/core/utils/Utils.h>using namespace TencentCloud;using namespace std;string Sign::Tc3Sign(const string &credDate, const string &serviceName, const string &signStr){string kKey = "TC3"+this->m_secretKey;string kDate = Utils::HmacSha256(kKey, credDate);string kService = Utils::HmacSha256(kDate, serviceName);string kSigning = Utils::HmacSha256(kService, "tc3_request");return Utils::HexEncode(Utils::HmacSha256(kSigning, signStr));}
SecretDate、SecretService 和 SecretSigning 是二进制的数据,可能包含不可打印字符,此处不展示中间结果。字段名称 | 解释 |
m_secretKey | 原始的 SecretKey,即 Gu5t9xGAR***********EXAMPLE。 |
credDate | 即 Credential 中的 Date 字段信息。此示例取值为 2019-02-25。 |
serviceName | 即 Credential 中的 Service 字段信息。此示例取值为 cvm。 |
signStr | 代签名字符串。 |
72e494ea8******************************************a96525168。Authorization =Algorithm + ' ' +'Credential=' + SecretId + '/' + CredentialScope + ', ' +'SignedHeaders=' + SignedHeaders + ', ' +'Signature=' + Signature
字段名称 | 解释 |
Algorithm | 签名方法,固定为 TC3-HMAC-SHA256。 |
SecretId | 密钥对中的 SecretId,即 AKIDz8krbsJ5**********mLPx3EXAMPLE。 |
CredentialScope | 见上文,凭证范围。此示例计算结果是 2019-02-25/cvm/tc3_request。 |
SignedHeaders | 见上文,参与签名的头部信息。此示例取值为 content-type;host。 |
Signature | 签名值。此示例计算结果是 72e494ea8******************************************a96525168。 |
TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168
POST https://cvm.tencentcloudapi.com/Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5**********mLPx3EXAMPLE/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=72e494ea8******************************************a96525168Content-Type: application/json; charset=utf-8Host: cvm.tencentcloudapi.comX-TC-Action: DescribeInstancesX-TC-Version: 2017-03-12X-TC-Timestamp: 1551113065X-TC-Region: ap-guangzhou{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}
#include <iostream>#include <iomanip>#include <sstream>#include <string>#include <stdio.h>#include <time.h>#include <openssl/sha.h>#include <openssl/hmac.h>using namespace std;string get_data(int64_t ×tamp){string utcDate;char buff[20] = {0};// time_t timenow;struct tm sttime;sttime = *gmtime(×tamp);strftime(buff, sizeof(buff), "%Y-%m-%d", &sttime);utcDate = string(buff);return utcDate;}string int2str(int64_t n){std::stringstream ss;ss << n;return ss.str();}string sha256Hex(const string &str){char buf[3];unsigned char hash[SHA256_DIGEST_LENGTH];SHA256_CTX sha256;SHA256_Init(&sha256);SHA256_Update(&sha256, str.c_str(), str.size());SHA256_Final(hash, &sha256);std::string NewString = "";for(int i = 0; i < SHA256_DIGEST_LENGTH; i++){snprintf(buf, sizeof(buf), "%02x", hash[i]);NewString = NewString + buf;}return NewString;}string HmacSha256(const string &key, const string &input){unsigned char hash[32];HMAC_CTX *h;#if OPENSSL_VERSION_NUMBER < 0x10100000LHMAC_CTX hmac;HMAC_CTX_init(&hmac);h = &hmac;#elseh = HMAC_CTX_new();#endifHMAC_Init_ex(h, &key[0], key.length(), EVP_sha256(), NULL);HMAC_Update(h, ( unsigned char* )&input[0], input.length());unsigned int len = 32;HMAC_Final(h, hash, &len);#if OPENSSL_VERSION_NUMBER < 0x10100000LHMAC_CTX_cleanup(h);#elseHMAC_CTX_free(h);#endifstd::stringstream ss;ss << std::setfill('0');for (int i = 0; i < len; i++){ss << hash[i];}return (ss.str());}string HexEncode(const string &input){static const char* const lut = "0123456789abcdef";size_t len = input.length();string output;output.reserve(2 * len);for (size_t i = 0; i < len; ++i){const unsigned char c = input[i];output.push_back(lut[c >> 4]);output.push_back(lut[c & 15]);}return output;}int main(){// 密钥参数string SECRET_ID = "AKIDz8krbsJ5**********mLPx3EXAMPLE";string SECRET_KEY = "Gu5t9xGAR***********EXAMPLE";string service = "cvm";string host = "cvm.tencentcloudapi.com";string region = "ap-guangzhou";string action = "DescribeInstances";string version = "2017-03-12";int64_t timestamp = 1551113065;string date = get_data(timestamp);// ************* 步骤 1:拼接规范请求串 *************string httpRequestMethod = "POST";string canonicalUri = "/";string canonicalQueryString = "";string canonicalHeaders = "content-type:application/json; charset=utf-8\\nhost:" + host + "\\n";string signedHeaders = "content-type;host";string payload = "{\\"Limit\\": 1, \\"Filters\\": [{\\"Values\\": [\\"\\\\u672a\\\\u547d\\\\u540d\\"], \\"Name\\": \\"instance-name\\"}]}";string hashedRequestPayload = sha256Hex(payload);string canonicalRequest = httpRequestMethod + "\\n" + canonicalUri + "\\n" + canonicalQueryString + "\\n"+ canonicalHeaders + "\\n" + signedHeaders + "\\n" + hashedRequestPayload;cout << canonicalRequest << endl;cout << "-----------------------" << endl;// ************* 步骤 2:拼接待签名字符串 *************string algorithm = "TC3-HMAC-SHA256";string RequestTimestamp = int2str(timestamp);string credentialScope = date + "/" + service + "/" + "tc3_request";string hashedCanonicalRequest = sha256Hex(canonicalRequest);string stringToSign = algorithm + "\\n" + RequestTimestamp + "\\n" + credentialScope + "\\n" + hashedCanonicalRequest;cout << stringToSign << endl;cout << "-----------------------" << endl;// ************* 步骤 3:计算签名 ***************string kKey = "TC3" + SECRET_KEY;string kDate = HmacSha256(kKey, date);string kService = HmacSha256(kDate, service);string kSigning = HmacSha256(kService, "tc3_request");string signature = HexEncode(HmacSha256(kSigning, stringToSign));cout << signature << endl;cout << "-----------------------" << endl;// ************* 步骤 4:拼接 Authorization *************string authorization = algorithm + " " + "Credential=" + SECRET_ID + "/" + credentialScope + ", "+ "SignedHeaders=" + signedHeaders + ", " + "Signature=" + signature;cout << authorization << endl;cout << "------------------------" << endl;string headers = "curl -X POST https://" + host + "\\n"+ " -H \\"Authorization: " + authorization + "\\n"+ " -H \\"Content-Type: application/json; charset=utf-8\\"" + "\\n"+ " -H \\"Host: " + host + "\\n"+ " -H \\"X-TC-Action: " + action + "\\n"+ " -H \\"X-TC-Timestamp: " + RequestTimestamp + "\\n"+ " -H \\"X-TC-Version: " + version + "\\n"+ " -H \\"X-TC-Region: " + region + "\\n"+ " -d '" + payload;cout << headers << endl;return 0;};
错误码 | 错误描述 |
AuthFailure.SignatureExpire | 签名过期。Timestamp 与服务器接收到请求的时间相差不得超过五分钟。 |
AuthFailure.SecretIdNotFound | 密钥不存在。请到控制台查看密钥是否被禁用,是否少复制了字符或者多了字符。 |
AuthFailure.SignatureFailure | 签名错误。可能是签名计算错误,或者签名与实际发送的内容不相符合,也有可能是密钥 SecretKey 错误导致的。 |
AuthFailure.TokenFailure | 临时证书 Token 错误。 |
AuthFailure.InvalidSecretId | 密钥非法(不是云 API 密钥类型)。 |
{"Response": {"TotalCount": 0,"InstanceStatusSet": [],"RequestId": "b5b41468-520d-4192-b42f-595cc34b6c1c"}}
Response 及其内部的 RequestId 是固定的字段,无论请求成功与否,只要 API 处理了,则必定会返回。RequestId 用于一个 API 请求的唯一标识,如果 API 出现异常,可以联系我们,并提供该 ID 来解决问题。TotalCount 和 InstanceStatusSet 均为 DescribeInstancesStatus 接口定义的字段,由于调用请求的用户暂时还没有云服务器实例,因此 TotalCount 在此情况下的返回值为0, InstanceStatusSet 列表为空。{"Response": {"Error": {"Code": "AuthFailure.SignatureFailure","Message": "The provided credentials could not be validated. Please check your signature is correct."},"RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6"}}
Error 的出现代表着该请求调用失败。Error 字段连同其内部的 Code 和 Message 字段在调用失败时是必定返回的。Code 表示具体出错的错误码,当请求出错时可以先根据该错误码在公共错误码和当前接口对应的错误码列表里面查找对应原因和解决方案。Message 显示出了这个错误发生的具体原因,随着业务发展或体验优化,此文本可能会经常保持变更或更新,用户不应依赖这个返回值。RequestId 用于一个 API 请求的唯一标识,如果 API 出现异常,可以联系我们,并提供该 ID 来解决问题。错误码 | 错误描述 |
AuthFailure.InvalidSecretId | 密钥非法(不是云 API 密钥类型)。 |
AuthFailure.MFAFailure | MFA 错误。 |
AuthFailure.SecretIdNotFound | 密钥不存在。 |
AuthFailure.SignatureExpire | 签名过期。 |
AuthFailure.SignatureFailure | 签名错误。 |
AuthFailure.TokenFailure | token 错误。 |
AuthFailure.UnauthorizedOperation | 请求未 CAM 授权。 |
DryRunOperation | DryRun 操作,代表请求将会是成功的,只是多传了 DryRun 参数。 |
FailedOperation | 操作失败。 |
InternalError | 内部错误。 |
InvalidAction | 接口不存在。 |
InvalidParameter | 参数错误。 |
InvalidParameterValue | 参数取值错误。 |
LimitExceeded | 超过配额限制。 |
MissingParameter | 缺少参数错误。 |
NoSuchVersion | 接口版本不存在。 |
RequestLimitExceeded | 请求的次数超过了频率限制。 |
ResourceInUse | 资源被占用。 |
ResourceInsufficient | 资源不足。 |
ResourceNotFound | 资源不存在。 |
ResourceUnavailable | 资源不可用。 |
UnauthorizedOperation | 未授权操作。 |
UnknownParameter | 未知参数错误。 |
UnsupportedOperation | 操作不支持。 |
UnsupportedProtocol | HTTPS 请求方法错误,只支持 GET 和 POST 请求。 |
UnsupportedRegion | 接口不支持所传地域。 |
文档反馈