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。 |
参数名称 | 类型 | 必选 | 描述 |
Action | String | 是 | 操作的接口名称。取值参考接口文档中输入参数公共参数 Action 的说明。例如云服务器的查询实例列表接口,取值为 DescribeInstances。 |
Region | String | - | 地域参数,用来标识希望操作哪个地域的数据。接口接受的地域取值参考接口文档中输入参数公共参数 Region 的说明。注意:某些接口不需要传递该参数,接口文档中会对此特别说明,此时即使传递该参数也不会生效。 |
Timestamp | Integer | 是 | 当前 UNIX 时间戳,可记录发起 API 请求的时间。例如1529223702,如果与当前时间相差过大,会引起签名过期错误。 |
Nonce | Integer | 是 | 随机正整数,与 Timestamp 联合起来,用于防止重放攻击。 |
SecretId | String | 是 | |
Signature | String | 是 | 请求签名,用来验证此次请求的合法性,需要用户根据实际的输入参数计算得出。具体计算方法参见下文“签名方法介绍” 。 |
Version | String | 是 | 操作的 API 的版本。取值参考接口文档中入参公共参数 Version 的说明。例如云服务器的版本 2017-03-12。 |
SignatureMethod | String | 否 | 签名方式,目前支持 HmacSHA256 和 HmacSHA1。只有指定此参数为 HmacSHA256 时,才使用 HmacSHA256 算法验证签名,其他情况均使用 HmacSHA1 验证签名。 |
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=72e494ea8******************************************a96525168" \\-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
const kDate = sha256(date, 'TC3' + SECRET_KEY)const kService = sha256(service, kDate)const kSigning = sha256('tc3_request', kService)const signature = sha256(stringToSign, kSigning, 'hex')
SecretDate
、SecretService
和 SecretSigning
是二进制的数据,可能包含不可打印字符,此处不展示中间结果。字段名称 | 解释 |
secretKey | 原始的 SecretKey,即 Gu5t9xGAR***********EXAMPLE 。 |
date | 即 Credential 中的 Date 字段信息。此示例取值为 2019-02-25 。 |
service | 即 CredentialScope 中的 Service 字段信息。此示例取值为 cvm 。 |
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"}]}
const crypto = require('crypto');function sha256(message, secret = '', encoding) {const hmac = crypto.createHmac('sha256', secret)return hmac.update(message).digest(encoding)}function getHash(message, encoding = 'hex') {const hash = crypto.createHash('sha256')return hash.update(message).digest(encoding)}function getDate(timestamp) {const date = new Date(timestamp * 1000)const year = date.getUTCFullYear()const month = ('0' + (date.getUTCMonth() + 1)).slice(-2)const day = ('0' + date.getUTCDate()).slice(-2)return `${year}-${month}-${day}`}function main(){// 密钥参数const SECRET_ID = "AKIDz8krbsJ5**********mLPx3EXAMPLE"const SECRET_KEY = "Gu5t9xGAR***********EXAMPLE"const endpoint = "cvm.tencentcloudapi.com"const service = "cvm"const region = "ap-guangzhou"const action = "DescribeInstances"const version = "2017-03-12"//const timestamp = getTime()const timestamp = 1551113065//时间处理, 获取世界时间日期const date = getDate(timestamp)// ************* 步骤 1:拼接规范请求串 *************const signedHeaders = "content-type;host"const payload = "{\\"Limit\\": 1, \\"Filters\\": [{\\"Values\\": [\\"\\\\u672a\\\\u547d\\\\u540d\\"], \\"Name\\": \\"instance-name\\"}]}"const hashedRequestPayload = getHash(payload);const httpRequestMethod = "POST"const canonicalUri = "/"const canonicalQueryString = ""const canonicalHeaders = "content-type:application/json; charset=utf-8\\n" + "host:" + endpoint + "\\n"const canonicalRequest = httpRequestMethod + "\\n"+ canonicalUri + "\\n"+ canonicalQueryString + "\\n"+ canonicalHeaders + "\\n"+ signedHeaders + "\\n"+ hashedRequestPayloadconsole.log(canonicalRequest)console.log("----------------------------")// ************* 步骤 2:拼接待签名字符串 *************const algorithm = "TC3-HMAC-SHA256"const hashedCanonicalRequest = getHash(canonicalRequest);const credentialScope = date + "/" + service + "/" + "tc3_request"const stringToSign = algorithm + "\\n" +timestamp + "\\n" +credentialScope + "\\n" +hashedCanonicalRequestconsole.log(stringToSign)console.log("----------------------------")// ************* 步骤 3:计算签名 *************const kDate = sha256(date, 'TC3' + SECRET_KEY)const kService = sha256(service, kDate)const kSigning = sha256('tc3_request', kService)const signature = sha256(stringToSign, kSigning, 'hex')console.log(signature)console.log("----------------------------")// ************* 步骤 4:拼接 Authorization *************const authorization = algorithm + " " +"Credential=" + SECRET_ID + "/" + credentialScope + ", " +"SignedHeaders=" + signedHeaders + ", " +"Signature=" + signatureconsole.log(authorization)console.log("----------------------------")const Call_Information = 'curl -X POST ' + "https://" + endpoint+ ' -H "Authorization: ' + authorization + '"'+ ' -H "Content-Type: application/json; charset=utf-8"'+ ' -H "Host: ' + endpoint + '"'+ ' -H "X-TC-Action: ' + action + '"'+ ' -H "X-TC-Timestamp: ' + timestamp.toString() + '"'+ ' -H "X-TC-Version: ' + version + '"'+ ' -H "X-TC-Region: ' + region + '"'+ " -d '" + payload + "'"console.log(Call_Information)}main()
参数名称 | 中文 | 参数值 |
Action | 方法名 | DescribeInstances |
SecretId | 密钥 ID | AKIDz8krbsJ5**********mLPx3EXAMPLE |
Timestamp | 当前时间戳 | 1465185768 |
Nonce | 随机正整数 | 11886 |
Region | 实例所在区域 | ap-guangzhou |
InstanceIds.0 | 待查询的实例 ID | ins-09dx96dg |
Offset | 偏移量 | 0 |
Limit | 最大允许输出 | 20 |
Version | 接口版本号 | 2017-03-12 |
{'Action' : 'DescribeInstances','InstanceIds.0' : 'ins-09dx96dg','Limit' : 20,'Nonce' : 11886,'Offset' : 0,'Region' : 'ap-guangzhou','SecretId' : 'AKIDz8krbsJ5**********mLPx3EXAMPLE','Timestamp' : 1465185768,'Version': '2017-03-12',}
Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5**********mLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12
cvm.tencentcloudapi.com
。实际的请求域名根据接口所属模块的不同而不同,详见各接口说明。请求方法 + 请求主机 +请求路径 + ? + 请求字符串
。GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8*****************MPLE&Timestamp=1465185768&Version=2017-03-12
Eli*****************cGeI=
# 实际调用,成功后可能如果是消费接口会产生计费(此处以Python语言为例发送get请求)resp = requests.get("https://" + endpoint, params=data)print(resp.url)
最终得到的请求串为https://cvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5**********mLPx3EXAMPLE&Signature=EliP***********************eI%3D&Timestamp=1465185768&Version=2017-03-12
字段名称 | 解释 |
endpoint | 服务地址, 例如: cvm.tencentcloudapi.com |
data | API 3.0 签名 V1 所举示例接口参数,注意:这里需要将计算的签名已键值对的形式加入 data 中 |
Eli*****************cGeI=
,最终得到的签名串请求参数(Signature)为:EliP***********************eI%3D
,它将用于生成最终的请求 URL。%XY
对特殊字符例如汉字进行百分比编码,其中“ X ”和“ Y ”为十六进制字符(0-9 和大写字母 A-F),使用小写将引发错误。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 = "AKIDz8krbsJ5**********mLPx3EXAMPLE"const SECRET_KEY = "Gu5t9xGAR***********EXAMPLE"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)console.log("-----------------------")// 3. 生成签名串params['Signature'] = sha1(SECRET_KEY, strSign)console.log(params['Signature'])console.log("-----------------------")// 4. 进行url编码并拼接请求urlconst req_url = get_req_url(params, endpoint)console.log(params['Signature'])console.log("-----------------------")console.log(req_url)}main()
错误码 | 错误描述 |
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 | 接口不支持所传地域。 |
本页内容是否解决了您的问题?