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开发测试流水线,这真的会大大方便各个对接腾讯云的开发者。