云 API PHP API

二、1. 服务地址（endpoint）

API 支持就近地域接入（例如：cvm 产品域名为 cvm.tencentcloudapi.com），也支持指定地域域名访问（例如：广州地域的域名为 cvm.ap-guangzhou.tencentcloudapi.com）。各产品支持地域不同，具体可参考产品文档的地域列表。例如，云服务器可参见 地域列表。

注意：对时延敏感的业务，建议指定带地域的域名。

三、2. 通信协议

腾讯云 API 的所有接口均采用 HTTPS 方式进行通信，提供高安全性的通信通道。

四、3. 请求方法

支持的 HTTP 请求方法：

·POST（推荐）

·GET

POST 请求支持的 Content-Type 类型：

·application/json（推荐），必须使用签名方法 v3（TC3-HMAC-SHA256）。

·application/x-www-form-urlencoded，必须使用签名方法 v1（HmacSHA1 或 HmacSHA256）。

·multipart/form-data（仅部分接口支持），必须使用签名方法 v3（TC3-HMAC-SHA256）。

注意：GET 请求的请求包大小不得超过32KB。POST 请求使用签名方法 v1（HmacSHA1、HmacSHA256）时不得超过1MB。POST 请求使用签名方法 v3（TC3-HMAC-SHA256）时最大支持10MB。

五、4. 字符编码

均使用 UTF-8 编码。

六、公共参数

注意：说明：

注意：公共参数是用于标识用户和接口签名的参数，每次请求均需要携带这些参数，才能正常发起请求。

七、签名方法 V3 公共参数

签名方法 v3（有时也称作 TC3-HMAC-SHA256）相比签名方法 v1 （部分文档简称为“签名方法”），更安全，支持更大的请求包，支持 POST JSON 格式，性能有一定提升，推荐使用该签名方法计算签名。使用方法见下文 “签名方法介绍” 。

八、签名方法 V1 公共参数

使用签名方法 v1 （有时会称作 HmacSHA256 和 HmacSHA1），公共参数需要统一放到请求串中。

九、地域列表

由于各个产品支持地域不同，具体详情请参考各产品文档中的地域列表。
例如，你可以参考云服务器的 地域列表。

十、PHP API 调用方式

腾讯云 API 会对每个请求进行身份验证，用户需要使用安全凭证，经过特定的步骤对请求进行签名（Signature），每个请求都需要在公共请求参数中指定该签名结果并以指定的方式和格式发送请求。

十一、步骤1：申请安全凭证

这篇使用的安全凭证为密钥，密钥包括 SecretId 和 SecretKey。每个用户最多可以拥有两对密钥。

·SecretId：用于标识 API 调用者身份，可以简单类比为用户名。

·SecretKey：用于验证 API 调用者的身份，可以简单类比为密码。

注意：用户必须严格保管安全凭证，避免泄露，否则将危及财产安全。如已泄露，请立刻禁用该安全凭证。

假设用户的 SecretId 和 SecretKey 分别是：AKIDz8krbsJ5**********mLPx3EXAMPLE 和 Gu5t9xGAR***********EXAMPLE。用户想查看广州区云服务器名为“未命名”的主机状态，只返回一条数据。

前往 API 密钥管理 页面，即可进行获取。如下：

注意：为降低密钥泄露的风险，自2023年11月30日起，对所有主账号、子账号的密钥，关闭查询 SecretKey 的功能，仅支持在创建时查看，请及时保存 SecretKey。

十三、1. 获取 API 3.0 V3 版本签名

签名方法 v3（TC3-HMAC-SHA256）功能上覆盖了以前的签名方法 v1，而且更安全，支持更大的请求，支持 json 格式，性能有一定提升，推荐使用该签名方法计算签名。


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

云 API 支持 GET 和 POST 请求。

·对于 GET 方法，只支持 Content-Type: application/x-www-form-urlencoded 协议格式。

·对于 POST 方法，目前支持 Content-Type: application/json 以及 Content-Type: multipart/form-data 两种协议格式，json 格式绝大多数接口均支持，multipart 格式只有特定接口支持，此时该接口不能使用 json 格式调用，参考具体业务接口文档说明。推荐使用 POST 请求，因为两者的结果并无差异，但 GET 请求只支持32KB以内的请求包。

下面以 查看实例列表 接口为例，分步骤介绍签名的计算过程。我们选择该接口是因为：

1. 云服务器默认已开通，该接口很常用；

2. 该接口是只读的，不会改变现有资源的状态；

3. 接口覆盖的参数种类较全，可以演示包含数据结构的数组如何使用。

十四、1. 拼接规范请求串

CanonicalRequest = HTTPRequestMethod + '\\n' + CanonicalURI + '\\n' + CanonicalQueryString + '\\n' + CanonicalHeaders + '\\n' + SignedHeaders + '\\n' + HashedRequestPayload

根据以上规则，示例中得到的规范请求串如下：

POST/content-type:application/json; charset=utf-8host:cvm.tencentcloudapi.comcontent-type;host35e9c5b0e3ae67532d3c9f17ead6c90222632e5b1ff7f6e89887f1398934f064

十五、2. 拼接待签名字符串

按如下格式拼接待签名字符串：

StringToSign = Algorithm + \\n + RequestTimestamp + \\n + CredentialScope + \\n + HashedCanonicalRequest

根据以上规则，示例中得到的待签名字符串如下：

TC3-HMAC-SHA25615511130652019-02-25/cvm/tc3_request5ffe6a04c0664d6b969fab9a13bdab201d63ee709638e2749d62a09ca18d7031

十六、3. 计算签名（伪代码）

$secretDate = hash_hmac("SHA256", $date, "TC3".$secretKey, true);$secretService = hash_hmac("SHA256", $service, $secretDate, true);$secretSigning = hash_hmac("SHA256", "tc3_request", $secretService, true);$signature = hash_hmac("SHA256", $stringToSign, $secretSigning);echo $signature.PHP_EOL;

派生出的密钥 SecretDate、SecretService 和 SecretSigning 是二进制的数据，可能包含不可打印字符，此处不展示中间结果。

此示例计算结果是 72e494ea8******************************************a96525168。

十七、4. 拼接 Authorization

按如下格式拼接 Authorization：

$authorization = $algorithm ." Credential=".$secretId."/".$credentialScope .", SignedHeaders=content-type;host, Signature=".$signature;echo $authorization.PHP_EOL;

根据以上规则，示例中得到的值为：

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"}]}

十八、5. API 3.0 签名 V3示例

<?php// 需要设置环境变量 TENCENTCLOUD_SECRET_ID，值为示例的 AKIDz8krbsJ5**********mLPx3EXAMPLE$secretId = getenv("TENCENTCLOUD_SECRET_ID");// 需要设置环境变量 TENCENTCLOUD_SECRET_KEY，值为示例的 Gu5t9xGAR***********EXAMPLE$secretKey = getenv("TENCENTCLOUD_SECRET_KEY");$host = "cvm.tencentcloudapi.com";$service = "cvm";$version = "2017-03-12";$action = "DescribeInstances";$region = "ap-guangzhou";// $timestamp = time();$timestamp = 1551113065;$algorithm = "TC3-HMAC-SHA256";// step 1: build canonical request string$httpRequestMethod = "POST";$canonicalUri = "/";$canonicalQueryString = "";$canonicalHeaders = "content-type:application/json; charset=utf-8\\n"."host:".$host."\\n";$signedHeaders = "content-type;host";$payload = '{"Limit": 1, "Filters": [{"Values": ["\\u672a\\u547d\\u540d"], "Name": "instance-name"}]}';$hashedRequestPayload = hash("SHA256", $payload);$canonicalRequest = $httpRequestMethod."\\n" .$canonicalUri."\\n" .$canonicalQueryString."\\n" .$canonicalHeaders."\\n" .$signedHeaders."\\n" .$hashedRequestPayload;echo $canonicalRequest.PHP_EOL;// step 2: build string to sign$date = gmdate("Y-m-d", $timestamp);$credentialScope = $date."/".$service."/tc3_request";$hashedCanonicalRequest = hash("SHA256", $canonicalRequest);$stringToSign = $algorithm."\\n" .$timestamp."\\n" .$credentialScope."\\n" .$hashedCanonicalRequest;echo $stringToSign.PHP_EOL;// step 3: sign string$secretDate = hash_hmac("SHA256", $date, "TC3".$secretKey, true);$secretService = hash_hmac("SHA256", $service, $secretDate, true);$secretSigning = hash_hmac("SHA256", "tc3_request", $secretService, true);$signature = hash_hmac("SHA256", $stringToSign, $secretSigning);echo $signature.PHP_EOL;// step 4: build authorization$authorization = $algorithm ." Credential=".$secretId."/".$credentialScope .", SignedHeaders=content-type;host, Signature=".$signature;echo $authorization.PHP_EOL;$curl = "curl -X POST https://".$host .' -H "Authorization: '.$authorization.'"' .' -H "Content-Type: application/json; charset=utf-8"' .' -H "Host: '.$host.'"' .' -H "X-TC-Action: '.$action.'"' .' -H "X-TC-Timestamp: '.$timestamp.'"' .' -H "X-TC-Version: '.$version.'"' .' -H "X-TC-Region: '.$region.'"' ." -d '".$payload."'";echo $curl.PHP_EOL;

十九、2. 获取 API 3.0 V1 版本签名

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

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

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

20、1. 对参数排序

首先对所有请求参数按参数名的字典序（ ASCII 码）升序排序。

上述示例参数的排序结果如下：

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

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

21、2. 拼接规范请求串

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

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

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

22、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=AKIDz8krbsJ5**********mLPx3EXAMPLE&Timestamp=1465185768&Version=2017-03-12

23、4. 计算签名（伪代码）

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

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

最终得到的签名串为：

EliP9YW3pW28FpsEdkXt/+WcGeI=

24、5. 获取调用信息并发送请求

# 实际调用，成功后可能如果是消费接口会产生计费(此处以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

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

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

25、6. 签名串编码

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

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

26、7. API 3.0 签名 V1示例

<?php// 需要设置环境变量 TENCENTCLOUD_SECRET_ID，值为示例的 AKIDz8krbsJ5**********mLPx3EXAMPLE$secretId = getenv("TENCENTCLOUD_SECRET_ID");// 需要设置环境变量 TENCENTCLOUD_SECRET_KEY，值为示例的 Gu5t9xGAR***********EXAMPLE$secretKey = getenv("TENCENTCLOUD_SECRET_KEY");$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);

27、API 2.0 签名

此签名现已不再维护，建议使用性能更优的 API 3.0 签名，如需使用，请直接在 API Explorer 的签名串生成>选择 API 2.0 签名版本进行操作。

28、签名失败

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

30、正确返回结果

以云服务器的接口查看实例列表 (DescribeInstances) 2017-03-12 版本为例，若调用成功，其可能的返回如下为：

{ "Response": { "TotalCount": 0, "InstanceStatusSet": [], "RequestId": "b5b41468-520d-4192-b42f-595cc34b6c1c" }}

·Response 及其内部的 RequestId 是固定的字段，无论请求成功与否，只要 API 处理了，则必定会返回。

·RequestId 用于一个 API 请求的唯一标识，如果 API 出现异常，可以联系我们，并提供该 ID 来解决问题。

·除了固定的字段外，其余均为具体接口定义的字段，不同的接口所返回的字段参见接口文档中的定义。此例中的 TotalCount 和 InstanceStatusSet 均为 DescribeInstancesStatus 接口定义的字段，由于调用请求的用户暂时还没有云服务器实例，因此 TotalCount 在此情况下的返回值为 0， InstanceStatusSet 列表为空。

31、错误返回结果

若调用失败，其返回值示例如下为：

{ "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 来解决问题。

32、公共错误码

返回结果中如果存在 Error 字段，则表示调用 API 接口失败。 Error 中的 Code 字段表示错误码，所有业务都可能出现的错误码为公共错误码，下表列出了公共错误码。