使用Postman玩转腾讯云

1. 简介

产品上云，那么作为产品的开发人员，其中一项重要的工作就是调用云厂商提供的API接口，来使用云产品。俗话说，工欲善其事，必先利其器。为了上云更轻松，我们需要一把利器来调用云厂商的API接口。接下来本文就向你介绍如何使用Postman这个API测试利器，来调用腾讯云API的接口，让你轻松玩转腾讯云。

2. Postman介绍

Postman是一个API开发协作平台。使用Postman的功能你可以简化构建API与开发测试流水线的每一步工作。最终你可以更快、更好地创建API。Postman有以下六大功能：API client， Automated Testing， Design & Mock，Documentation，Monitors和Workspaces。

作为API client，使用Postman发送HTTP请求非常简单与直接，其支持REST，SOAP，GraphQL等形式的请求。而现在的API都采用RESTFul的形式，使用Postman进行HTTP API的测试是再好不过的工具了。

2.1 Postman发送HTTP请求

下图展示了Postman中发送一个HTTP请求测试用例的几个组成部分。HTTP Request和Response都非常直观地展示在界面中。

如果只能发送简单的HTTP请求，那Postman也不算好用。下面我们介绍两个让Postman更强大更好用的功能，这也是我们能够玩转腾讯云必不可少的功能。

2.2 Postman中定义变量

在Postman中可以定义变量，最常用的有环境变量和全局变量。我们可以通过定义变量在请求中将一些参数使用变量代替，这使得请求的模板不用变动，只需改变变量的值，就能实现改变请求内容的功能。

如下图所示，我们Request的Body中使用了{{version}}变量，在发送请求时，Postman就会到环境变量和全局变量中寻找{{version}}变量的值，并进行替换。

2.3 Pre-Request Script和Test Script

在Postman中我们可以使用JavaScript编写一些脚本，在发送HTTP请求之前和收到HTTP响应之后，分别完成一些工作。比如在请求前动态地添加一些HTTP 请求Headers，收到响应后判断回包中的内容是否符合预期，以达到测试请求结果的目的。脚本在使用范围上分为COLLECTION级别，FOLDER级别和REQUEST级别脚本。

下图清晰地展现了不同级别的Pre-Request Script和Test Script的生效顺序和生效时间。

在Postman的脚本中，我们不仅使用环境变量和全局变量，还可以使用Postman提供的一些JavaScript库进行一些复杂的运算，比如生成签名、对请求数据中的某些字段进行base64编码等工作。

3. Postman调用腾讯云API

腾讯云API，可以使开发者简单快捷地使用腾讯云产品。相比与web控制台，API更直接高效。我们可以充分利用Postman变量和脚本功能，用其调用腾讯云的API，来使用云服务器、批量计算、弹性伸缩等全部云服务。

3.1 腾讯云API简介

为了创建HTTP请求，那么我们就需要介绍一下腾讯云API中的几个基本概念。

1. 服务地址：腾讯云API支持全地域就近接入，可以让开发者更快地连接腾讯云产品。服务地址的组成方式如：cvm.tencentcloudapi.com。其构造规则为service+endpoint。service为每个云产品的名称如云服务器“cvm”，endpoint固定为“.tencentcloudapi.com”。

2. 通信协议：HTTPS

3. 请求方法：POST（推荐）和GET。其中 POST 请求支持的 Content-Type 类型：为application/json（推荐），必须使用 TC3-HMAC-SHA256 签名方法。

4. API公共参数：

公共参数名

含义

X-TC-Action

操作的接口名称

X-TC-Region

地域参数

X-TC-Timestamp

当前 UNIX 时间戳

X-TC-Version

操作的 API 的版本，请参见每个云产品的API文档

Authorization

HTTP 标准身份认证头部字段，例如：
TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f102

其中，
- TC3-HMAC-SHA256：签名方法，目前固定取该值；
- Credential：签名凭证，AKIDEXAMPLE 是 SecretId；Date 是 UTC 标准时间的日期，取值需要和公共参数 X-TC-Timestamp 换算的 UTC 标准时间日期一致；service 为产品名，通常为域名前缀，例如域名 cvm.tencentcloudapi.com 意味着产品名是 cvm。本产品取值为 cvm；
- SignedHeaders：参与签名计算的头部信息，content-type 和 host 为必选头部；
- Signature：签名摘要。

5. HTTP请求数据：采用推荐的json格式数据。

3.2 Postman构造腾讯云请求流程

从上面的介绍我们可以看到，若想向腾讯云发送HTTP请求，需要构造请求数据和公共参数。下面我们就详细介绍如何使用Postman构造请求。

3.2.1 collection Pre-request Script

collection Pre-request Script中定义了build_request函数，其作用是根据腾讯云官方文档提供的方法来生成HTTP Request头部的字段。其中重点是生成签名，这样才能通过腾讯云的身份验证，访问腾讯云各个云产品。将此功能放到collection中也是为了达到代码重用的目的，这样该collection中每个Request仅定义请求参数即可。

collection Pre-request Script 具体代码如下：

pm.globals.set("TencentCloudApi", function TencentCloudApi()  {    let tencentcloudapi = {};        function sha256_hex(msg) {        var utf8_str = CryptoJS.enc.Utf8.parse(msg);        var sha256_str = CryptoJS.SHA256(utf8_str);        var sha256_hex_str = CryptoJS.enc.Hex.stringify(sha256_str);        return sha256_hex_str;    }        function sign_hmac256(key, msg) {        var utf8_str = CryptoJS.enc.Utf8.parse(msg);        var hash_str = CryptoJS.HmacSHA256(utf8_str, key);        return hash_str;    }        function sign_hmac256_hex(key, msg) {        var utf8_str = CryptoJS.enc.Utf8.parse(msg);        var hash_str = CryptoJS.HmacSHA256(utf8_str, key);        var hex_str = CryptoJS.enc.Hex.stringify(hash_str);        return hex_str;            }        function get_pm_env_or_global(key) {        return (pm.environment.get(key) !== undefined)? pm.environment.get(key): pm.globals.get(key);    }        tencentcloudapi.build_request = function build_request(params) {        var service = pm.environment.get("service");        var host = service + get_pm_env_or_global("tencentcloud_endpoint");        var region = pm.environment.get("region");        var version = pm.environment.get("version");        var action = request.headers["X-TC-Action"];        var algorithm = "TC3-HMAC-SHA256";        var timestamp = Math.round(Date.now() / 1000);        var d = new Date();        var date = d.toISOString().split('T')[0];                // step 1：create canonical_request        var http_request_method = "POST";        var canonical_uri = "/";        var canonical_querystring = "";        // tencentcloud suggests to add charset=utf-8, however postman will set content-type to        // application/json when request data format json is selected. So we don't add charset.        //content_type = "application/json; charset=utf-8";        var content_type = "application/json";        var request_json_payload = JSON.stringify(params);        var canonical_headers = "content-type:" + content_type + "\nhost:" + host + "\n";        var signed_headers = "content-type;host";        var hashed_request_payload = sha256_hex(request_json_payload);                var canonical_request = http_request_method   + "\n" +                                canonical_uri         + "\n" +                                canonical_querystring + "\n" +                                canonical_headers     + "\n" +                                signed_headers        + "\n" +                                hashed_request_payload;        //console.log('canonical_request');        //console.log(canonical_request);                // step 2：create signing_string        var credential_scope = date + "/" + service + "/" + "tc3_request";        var hashed_canonical_request = sha256_hex(canonical_request);                var string_to_sign = algorithm            + "\n" +                             timestamp.toString() + "\n" +                             credential_scope     + "\n" +                             hashed_canonical_request;        //console.log('string_to_sign');        //console.log(string_to_sign);                // step 3：calculate signature        var secret_id = get_pm_env_or_global("secret_id");        var secret_key = get_pm_env_or_global("secret_key");        var secret_date_key = CryptoJS.enc.Utf8.parse("TC3" + secret_key);        var secret_date = sign_hmac256(secret_date_key, date);        var secret_service = sign_hmac256(secret_date, service);        var secret_signing = sign_hmac256(secret_service, "tc3_request");        var signature = sign_hmac256_hex(secret_signing, string_to_sign);        //console.log("signature");        //console.log(signature);                // step 4：create authorization        var authorization = algorithm + " " +                            "Credential=" + secret_id + "/" + credential_scope + ", " +                            "SignedHeaders=" + signed_headers + ", " +                            "Signature=" + signature;        //console.log("authorization");        //console.log(authorization);                // step 5: add HTTP headers        pm.request.headers.add("X-TC-Region:"+region);        pm.request.headers.add("X-TC-Timestamp:"+timestamp);        pm.request.headers.add("X-TC-Version:"+version);        pm.request.headers.add("Authorization:"+authorization);        pm.request.headers.add("Host:"+host);                // step 6: set environment variables using in request        pm.environment.set("host", host);        pm.environment.set("request_json_payload", request_json_payload);    };        return tencentcloudapi;} + 'TencentCloudApi();');

3.2.2 Request Pre-request Script

有了上面定义的build_request函数，每个Request指定请求的接口名和请求参数即可。具体如下所示：

// [腾讯云](https://l.gushuji.site/tencent)API的接口名， 如RunInstancesvar action = "RunInstances";pm.request.headers.add("X-TC-Action:"+action); var params = {    //参照[腾讯云](https://l.gushuji.site/tencent)API文档，填入请求的参数}; eval(pm.globals.get('TencentCloudApi')).build_request(params);

3.2.3 环境变量

必填的环境变量有secret_id和secret_key（腾讯云API密钥id和key），region，service，tencentcloud_endpoint和version。具体如下图所示：

3.2.4 HTTP请求Body

因为我们在build_request函数中将请求的数据写入到环境变量的request_json_payload中了，所以Body中只需填入{{request_json_payload}},格式选择JSON即可。如下图所示：

4. Postman玩转腾讯云

有了以上的准备后，我们就可以用Postman玩转腾讯云了。下面我们就以创建云服务器，查询云服务器和销毁云服务器这三个最常用的操作，介绍一下具体流程。

4.1 创建云服务器-RunInstances

4.1.1 RunInstances Pre-request Script

例如我们在广州四区创建一台机型为S3.SMALL1，操作系统为CentOS7.4，系统盘为50G高效云硬盘，按量计费的云服务器。

RunInstances Request的Pre-request Script中添加如下接口参数即可。

var action = "RunInstances";pm.request.headers.add("X-TC-Action:"+action); var params = {    "Placement": {        "Zone": "ap-guangzhou-4"    },    "ImageId": "img-8toqc6s3",// CentOS 7.4    "InstanceChargeType": "POSTPAID_BY_HOUR",    "InstanceType": "SA1.SMALL1",    "SystemDisk": {        "DiskType": "CLOUD_PREMIUM",        "DiskSize": 50    },    "InstanceName": "Postman-create-CVM"}; eval(pm.globals.get('TencentCloudApi')).build_request(params);

4.1.2 RunInstances Test Script

在RunInstances Request的Test Script中我们把InstanceId写入到环境变量instance_id中，这样我们就可以在其他接口中复用该环境变量了。

Test Script具体内容如下：

var jsonData = pm.response.json();if (jsonData.Response.InstanceIdSet[0]) {    postman.setEnvironmentVariable("instance_id", jsonData.Response.InstanceIdSet[0]);}

4.1.3 发送请求后的结果

Postman中点击Send后，我们收到腾讯云返回的实例Id。

登录到腾讯云的控制台，我们看到该云服务器已经创建出来。

4.2 查看云服务器-DescribeInstances

有了RunInstances Requst中创建好的instance_id环境变量，使用DescribeInstances接口查询实例就非常简单了。

其Pre-request Script如下：

var action = "DescribeInstances";pm.request.headers.add("X-TC-Action:"+action); var params = {    "InstanceIds": [pm.environment.get("instance_id")]};eval(pm.globals.get('TencentCloudApi')).build_request(params);

结果如下：

4.3 退还云服务器-TerminateInstances

若想退还云服务器，我们只需调用TerminateInstances接口，还可以利用环境变量中的instance_id。

其Pre-request Script如下：

var action = "TerminateInstances";pm.request.headers.add("X-TC-Action:"+action); var params = {    "InstanceIds": [pm.environment.get("instance_id")]};eval(pm.globals.get('TencentCloudApi')).build_request(params);

结果如下：

5. 总结

通过在Postman中编写Pre-Request Script，我们只要参照腾讯云每个产品的API文档，在Pre-Request Script中添加接口参数，就可以非常方便地使用腾讯云提供的各种服务了。如果我们再利用Postman的Test Script和Run Collection等功能，就能打造一套API开发测试流水线，这真的会大大方便各个对接腾讯云的开发者。