能力使用者接入指引

1、整体接入流程

（1）能力订购流程：在能力门户中已上架的能力，能力使用者可根据自身需求在能力门户中完成能力订购，通过此流程，可获取某能力的使用权限；
（2）应用接入流程：能力使用者在能力门户中订购完成后，需完成环境准备、接入开发、联调测试、发布上线等工作，完成应用的接入；
（3）能力生效流程：在完成能力订购和应用接入流程后，则进入到能力的生效流程，通过此流程能力使用者打开生产环境的能力调用开关，并开始计费。

2、应用接入流程

（1）环境准备

物联网IoT Gateway门户提供两套环境，分别是：
1）、沙箱环境：功能与生产环境一致，可作接口联调与业务测试。(暂不可用)
例 沙箱地址：https://gwtest.10646.cn/api/XXXXX/v1.0
2）、生产环境：提供生产环境的能力调用
例 生产地址 :https://gwapi.10646.cn/api/XXXXX/v1.0

（2）授权介绍

 1）、当应用创建成功后，分配app_id和app_secret，不同的环境有不同app_secret,查看路径为“用户主页🡪我的应用列表页🡪应用详情查看页”如下图；因沙箱环境暂不可用,请使用生产环境app_secret进行调用.![](https://cdn.nlark.com/yuque/0/2022/png/26267527/1649467922456-fce488f2-f15f-4d1d-b87f-87a6e0444fea.png#)<br />2）、能力调用时，需要使用app_secret对请求报文进行签名，请求参数中需要传递app_id进行权限校验，app_id在应用上线后不可变更为全局唯一，app_secret在应用上线后可以在能力门户界面中进行变更；<br />3）、签名：调用api值需要进行签名token值的校验，服务器也会对该请求参数进行验证是否合法的；签名值token是将请求源串以及密钥根据一定签名方法生成的签名值。物联网IoT Gateway提供token算法。应用的请求中必须加上token参数，用于应用的身份验证和请求的防篡改验证。token算法如下：<br />a、根据系统参数名称（除token）将所有请求系统参数按照字母先后顺序排序:<br />key + value .... key + value <br />例如：请求URL为：<br />https://host:port/api/customer/cuseser/v1；<br />将系统参数值<br />app_id=abc,timestamp=2016-04-12 15:06:06 100，trans_id=20160412150606100335423<br />参数名和参数值链接后，得到拼装字符串：<br />app_idabctimestamp2016-04-12 15:06:06 100trans_id20160412150606100335423<br />b、拼接app_secret<br />app_secret为应用申请时分配的密钥，不在URL中传递，双方配置在自己系统中，用于计算token值，增强安全性。<br />app_secret值拼接到上面的字串中后面，加入app_secret值为B2732427，最终得到：<br />app_idabctimestamp2016-04-12 15:06:06 100trans_id20160412150606100335423B2732427<br />c、采用国密SM3对源串进行加密处理 <br />SM3(app_idabctimestamp2016-04-12 15:06:06 100trans_id20160412150606100335423B2732427)<br />d、将上步计算得到结果以16进制小写字母输出，即为签名值

（3）调用方式

通过HTTPS POST请求方式进行API调用，并根据API规范拼接正确的URL，就能够使用相应能力，取得相应数据。

（4）调用参数

发起API调用的请求有二类参数：系统参数、应用参数，系统参数与应用参数以POST的方式把提交的数据则放置在HTTPS包的包体中传输；
1）、系统参数（报文头）

2）、应用参数（报文体）
应用参数参照《中国联通物联网IoT Gateway API规范》，即对应的能力手册。
示例：
请求报文：
{
“app_id”:”xxxxxxxxx”,
“timestamp”:”2017-06-20 00:00:00 041”,
“trans_id”:”20170620000000041627208”,
“token”:”dsfasdgasdgasdgasgsagdasdgas”,
“data”:{
“type”:”msisdn”,
“msid”:”12312412412412”
}
}
返回报文：
{
“status”:”0”,
“message”:”OK”,
“data”:{
“pos”:{
“x”:”30 16 28.308N”,
“y”:”45 15 33.444E”
}
}
}
3）、参数说明
名称：参数英文名称，用于HTTPS-POST方式JSON报文中节点的名称，所有节点名称都小写。
类型：标识此节点的参数类型

必填?：Y为必填，N为选填
备注：为具体描述此参数的业务和取值范围

（5）SDK使用

本SDK实现了调用Gateway能力的客户端，封装了签名算法，重试等实现，开发者可通过CommonJsonRequest类实现基本的Json请求的封装，如有其它需求，亦可通过继承BaseIoTGatewayRequest自定义实现。
1）、该sdk为一个java工程，可以导入到设计器中，进行查看、运行（允许主函数在类UsernumberCheckExample中，请重点关注代码中的注释）；
2）、在调用具体的api时，需要填写系统参数、公共参数、业务参数
3）、系统参数：
请求地址: 协议类型、域名、path需要根据能力门户我的能力->订购列表->能力详情中的apiurl填写，域名会区分测试、（不一定具有测试环境）和正式环境；
app_id: 在门户创建完应用产生的app_id；
app_secrect: 在门户创建完应用产生的app_secrect，生产环境的app_secrect一定会有，但是沙箱环境的app_secrect需要根据实际的情况选取；

4）、公共参数：
Api name：截取调用地址中api/和/v中间部分；
Api ver（版本号）：截取调用地址最后一部分后去掉第一个小v；
5）、业务参数（需要发给能力提供者的参数）：
所有需要发送给能力提供者的参数（系统参数除外）都必须放在业务参数中，以key-value的形式存放
6）、下载及样例
下载地址：
样例：
public static void main(String[] args) throws ApiException
{
IoTGatewayClient client = new IoTGatewayClient(“https://gwtest.10646.cn/api/“, “presetapp”,
“presetappsecrect”);
client.setConnectTimeout(2000);//连接超时时长设置（单位：毫秒），可以不设置，默认两秒
// client.setReadTimeout(30000);//读取超时时长设置（单位：毫秒），可以不设置，默认三十秒
//client.setRetryCount(1);//连接超时后，重试次数 0：不重试 1：重试一次 以此类推。可以不设置，默认不重试
CommonJsonRequest request = new CommonJsonRequest();
// 完整的url：https://gwtest.10646.cn/api/GetAccountIdByAcctName_V1_0Main/vV1.0
request.setApiName(“GetAccountIdByAcctNameV1_0Main”);
request.setApiVer(“V1.0”);

/
业务参数，需要发给能力提供者
/
Map params = new HashMap();
params.put(“messageId”, “1”);
params.put(“version”, “V1.0”);
params.put(“licenseKey”, “ec9debf4-4768-49ac-b697-20d205a160ff”);
params.put(“accountName”, “145_TEST”);
params.put(“username”, “ApiRoot145”);
params.put(“password”, “T@t123456”);
request.setParams(params);
CommonJsonResponse response = client.execute(request);
System._out.println(“发送请求流水号：” + request.getTransId());
System.out.println(“请求报文：” + request.getReqText());
System.out.println(“请求是否被成功处理:” + response.isSuccess());
Map data = response.getData();
if (response.isSuccess()){
// System.out.println(“成功返回业务参数：” + data.get(“checkresult”));
System.out.println(“成功返回业务参数：” + data);
}
else
{
System.out**.println(“处理失败返回消息：” + data);
}
}

四、接入测试

1、测试方法

物联网IoT Gateway提供用户自助测试区（沙箱环境），应用使用自身开发工具，输入相关参数，访问API的URL，物联网IoT Gateway根据请求报文返回模拟结果数据。

2、系统错误返回码

通过Gateway调用能力时，产生错误的区域有两个，为了便于讨论，对其分别简单命名。Gateway自身产生的错误，称之为网关错误；能力提供者返回的错误，称之为业务错误。
样例
成功应答：
{
“status”:”0”,
“message”:”OK”,
“data”:{
“pos”:{
“x”:”30 16 28.308N”,
“y”:”45 15 33.444E”
}
}
}

网关错误样例：
{
“error”:{
“status”:”31”,
“message”:”API标识错误或API未部署发起：”
}
}
请求地址不存在样例：
{
“status”:”001”,
“message”:”一般错误”
}

业务错误样例：
{
“status”:”0”,
“message”:”OK”,
“data”:{
“status”:”001”,
“message”:”一般错误”
}
}

（1）HTTP错误

HTTP层在IoT Gateway用作传输协议，且HTTP错误码空间已有定义且范围有限，只对应用级错误做简单映射。

（2）Gateway系统错误