文档首页 > > 开发指南> 应用侧开发> 使用SDK对接> Java SDK使用指南

Java SDK使用指南

分享
更新时间: 2019/09/23 GMT+08:00

本文以提供的北向Java SDK Demo为例说明如何使用JAVA SDK与物联网平台对接,包括证书配置及回调等。Demo以Java工程为例,每个类(除工具类外)都包含了main方法,可单独运行,旨在演示如何调用SDK接口。

导入Demo工程

  1. 将下载的JAVA SDK Demo解压到本地。
  2. 打开eclipse,选择菜单File > Import ,再选择Maven > Existing Maven Projects,单击“Next”

  3. 单击“Browse”,选择demo解压后的路径,然后单击“Finish”

初始化及证书配置

新建一个NorthApiClient实例,设置好ClientInfo(包括平台IP、端口、appId和密码),再初始化证书。

  • 平台IP、端口、appId和密码都是从配置文件./src/main/resources/application.properties中读取的,因此,当这些信息发生变化时,只要修改配置文件,不用修改应用服务器的代码。
  • 本章节所指的证书是平台提供的,在调用平台接口过程中使用;一般情况下,与回调使用的证书不一样。
  • 使用测试证书:
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    NorthApiClient northApiClient = new NorthApiClient();
    
    PropertyUtil.init("./src/main/resources/application.properties");
    
    ClientInfo clientInfo = new ClientInfo();
    clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));
    clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));
    clientInfo.setAppId(PropertyUtil.getProperty("appId"));
    clientInfo.setSecret(PropertyUtil.getProperty("secret"));
    
    northApiClient.setClientInfo(clientInfo);
    northApiClient.initSSLConfig();//默认使用测试证书,且不进行主机名校验
    
  • 如果不使用测试证书,可使用指定证书(如商用证书):
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    NorthApiClient northApiClient = new NorthApiClient();
    
    PropertyUtil.init("./src/main/resources/application.properties");
    
    ClientInfo clientInfo = new ClientInfo();
    clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));
    clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));
    clientInfo.setAppId(PropertyUtil.getProperty("appId"));
    clientInfo.setSecret(getAesPropertyValue("secret"));
    
    SSLConfig sslConfig= new SSLConfig();
    sslConfig.setTrustCAPath(PropertyUtil.getProperty("newCaFile"));
    slConfig.setTrustCAPwd(getAesPropertyValue("newCaPassword"));
    slConfig.setSelfCertPath(PropertyUtil.getProperty("newClientCertFile"));
    slConfig.setSelfCertPwd(getAesPropertyValue("newClientCertPassword"));
    
    northApiClient.setClientInfo(clientInfo);
    northApiClient.initSSLConfig(sslconfig); //使用指定的证书,且默认使用严格主机名校验
    
    使用指定证书时,如果不使用严格主机名校验,在调用 northApiClient.initSSLConfig(sslconfig)之前可以自行设置主机名校验方法:
    1
    2
    3
    4
    5
    6
    7
    northApiClient.setHostnameVerifier(new HostnameVerifier() {
        public boolean verify(String arg0, SSLSession arg1) {
            // 自定义主机名校验
            ……
            return true;
        }
    });
    

    主机名校验方法应以安全为原则,不应该直接返回true。

业务接口调用方法

设置好NorthApiClient实例后才能调用其他业务接口。以如下几个接口为例说明如何调用业务接口。

鉴权

1
2
3
4
5
6
7
8
//得到NorthApiClient实例后,再使用northApiClient得到鉴权类实例
Authentication authentication = new Authentication(northApiClient);

//调用鉴权类实例authentication提供的业务接口,如getAuthToken
AuthOutDTO authOutDTO = authentication.getAuthToken();

//从返回的结构体authOutDTO中获取需要的参数,如accessToken
String accessToken = authOutDTO.getAccessToken();

订阅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
//得到NorthApiClient实例后,再使用northApiClient得到订阅类实例
SubscriptionManagement subscriptionManagement = new SubscriptionManagement(northApiClient);

//先设置好subDeviceData的第一个入参SubDeviceDataInDTO结构体
SubDeviceDataInDTO sddInDTO = new SubDeviceDataInDTO();
sddInDTO.setNotifyType("deviceDataChanged");
//需要根据实际情况修改回调的ip和端口
ddInDTO.setCallbackUrl("https://XXX.XXX.XXX.XXX:8099/v1.0.0/messageReceiver");
try {
    //调用订阅类实例subscriptionManagement提供的业务接口,如subDeviceData
    SubscriptionDTO subDTO = subscriptionManagement.subDeviceData(sddInDTO, null, accessToken);
    System.out.println(subDTO.toString());
} catch (NorthApiException e) {
    System.out.println(e.toString());
}

注册设备

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
//得到NorthApiClient实例后,再使用northApiClient得到设备管理类实例
DeviceManagement deviceManagement = new DeviceManagement(northApiClient);

//设置好注册设备接口的第一个入参RegDirectDeviceInDTO2结构体
RegDirectDeviceInDTO2 rddInDTO = new RegDirectDeviceInDTO2();
String nodeid = "86370303XXXXXX"; //this is a test imei
String verifyCode = nodeid;
rddInDTO.setNodeId(nodeid);
rddInDTO.setVerifyCode(verifyCode);
rddInDTO.setTimeout(timeout);

//调用设备管理类实例deviceManagement提供的业务接口,如regDirectDevice
RegDirectDeviceOutDTO rddod = deviceManagement.regDirectDevice(rddInDTO, null, accessToken);

//从返回的结构体rddod中获取需要的参数,如deviceId
String deviceId = rddod.getDeviceId();
说明:

关于哪些参数需要设置,请查看《北向JAVA SDK API参考》对于可选参数,如果业务不需要,可以不设置或者设置为null。

回调接口实现及证书制作

回调接口实现

新建一个类并继承 PushMessageReceiver,可以参考Demo中的 PushMessageReceiverTest类,需要接收哪一类消息就重写对应的方法,如:
1
2
3
4
5
@Override
public void handleDeviceAdded(NotifyDeviceAddedDTO body) {
    System.out.println("deviceAdded ==> " + body);
    //TODO deal with deviceAdded notification
}
说明:
  • 接收到平台推送的消息后,开发者需要根据业务进行处理,但不建议进行复杂计算、I/O操作或者可能长时间等待的动作,可以先写数据库,应用进入相应界面或者刷新界面再从数据库取数据并进行数据处理。
  • 回调路径已在SDK中设置好了,所以在订阅时要注意订阅对应的回调地址,具体可参考《北向JAVA SDK API参考》文档中消息推送章节的接口。
  • 回调的IP地址则是服务器的地址,需要是公网地址。
  • Demo工程的回调端口配置在src\main\resource\application.properties中:
    1
    2
    #specify the port of the web application
    server.port=8099
    

回调证书制作

本章节以自签名证书为例。如果是使用商用证书,请直接向CA机构申请。

  1. 打开windows命令行窗口,输入where java,找到jdk所在路径,进入jdk的bin路径。

    1
    2
    where java
    cd /d {jdkbin路径}
    

  2. 使用如下命令生成tomcat.keystore文件。

    1
    keytool -genkey -v -alias tomcat -keyalg RSA -keystore tomcat.keystore -validity 36500
    

    • 如果jdk的bin目录下已有tomcat.keystore,建议先将已有的tomcat.keystore移到别的路径下。
    • “您的名字与姓氏是什么”要输入应用服务器的IP或域名。
    • <tomcat>的密钥口令要与密钥库口令设置一致(最后一步按回车即可),输入的密钥库口令要记住,后续配置会使用到

  3. 将物联网平台提供的根证书ca.pem放到jdk的bin目录下,并使用如下命令将其加到tomcat.keystore的信任证书链中。

    1
    keytool -import -v -file ca.pem -alias iotplatform_ca -keystore tomcat.keystore
    

    输入密钥库口令,查看导入的证书内容,确认无误后,输入y即可。

    说明:
    • 平台的测试根证书ca.pem可以在JAVA SDK包的cert目录下找到。
    • 将物联网平台提供的根证书ca.pem加到tomcat.keystore的信任证书链后,由ca.pem签发的子证书就能得到应用服务器的信任。

  4. 将tomcat.keystore放到Demo工程目录下,例如:src\main\resources,打开src\main\resource\application.properties,添加如下配置。其中,server.ssl.key-store 为tomcat.keystore 所在路径,server.ssl.key-store-password为密钥库口令。

    #one-way authentication (server-auth)
    server.ssl.key-store=./src/main/resources/tomcat.keystore
    server.ssl.key-store-password=741852963.

  5. 右键单击PushMessageReceiverTest,选择Run As > Java Application ,运行Demo中的PushMessageReceiverTest类。运行结果如下:

    说明:

    当有数据推送到应用服务器时,就会进入相应的回调函数中。

回调证书导出

  1. 使用浏览器打开回调地址https://server:8099/v1.0.0/messageReceiver,以Google为例,并查看证书。

    server是应用服务器的地址(即本机地址),8099是在application.properties中配置的端口。

  2. 系统将弹出证书窗口,选择“详细信息”,单击“复制到文件”

  3. 单击“下一步”,进入“导出文件格式”界面,选择“Base64编码”,然后单击“下一步”

  4. 指定证书的保存路径,完成证书导出。

    1. “要导出的文件”界面,单击“浏览”,选择一个路径,输入文件名,单击“保存”,回到证书导出向导,单击“下一步”

    2. 单击“完成”,完成证书导出。

    如果应用服务器最后部署到云上,可能会有多级证书,建议在部署完成后再导出证书。此时需要将证书链上面几级的证书一一导出

  5. 若存在多级证书,需一一导出。

    1. “证书”窗口,选择“证书路径”,查看多级证书,选中证书路径中的某个证书,单击“查看证书”

    2. 系统将弹出证书窗口,选择“详细信息”,然后重复上述导出证书的步骤,导出已选证书。

  6. 使用文本编辑器,将所有导出的证书以首尾相连的方式,合并为一个.pem格式的文件。该文件需要上传到物联网平台相应的应用下。

回调证书上传

  1. 登录开发中心,进入相关项目。
  2. 选择应用 > 对接信息,单击“证书管理”
  3. 单击“添加”,上传证书。

业务接口调用流程及注意事项

  • 请按如下流程调用业务接口。

  • Demo中使用的Profile如下图所示,只有一个Brightness服务,Brightness服务下有一个brightness属性和一个PUT命令。在调用创建设备命令或设备服务调用等接口时,如果不是使用以下Profile内容,请将相关服务、属性或者命令名称修改为相应的名称。

  • 创建新的Profile方法:

    登录开发者中心,选择产品 > 产品开发 > 添加 > 自定义产品,点击“自定义产品”,进入“设置产品信息”页面。填写“产品名称”“型号”“厂商ID”“所属行业”“设备类型”“接入应用层协议类型”等产品信息,点击“创建”。然后点击“+新建服务”(根据设备功能添加属性和命令)最后点击“保存”

    说明:

    建议在定义好Profile后再调用接口注册设备。

  • 修改设备信息接口使用到的字段值如“设备类型”“厂商名”“厂商ID”“设备型号”要与Profile定义的保持一致。
  • accessToken可以由SDK管理,也可由第三方应用自行管理,具体参考具体可参考《JAVA SDK API参考文档》应用安全接入 > 定时刷新token 章节的说明。

SDK独立运行测试

SDK包中提供了可独立运行的jar包,用于测试平台Restful接口。可独立运行测试的jar包在testSDK目录下:

图1 可独立运行的jar包
  1. 修改config.properties后再双击运行runMe.bat即可进行测试。

    图2 修改config.properties

  2. 如果使用商用证书,请直接将证书放在testSDK目录下面(证书名字不可以与ca.jks或者outgoing.CertwithKey.pkcs12相同),并在config.properties中配置证书名及密码;如果使用测试证书,则不需要修改config.properties中的证书信息。
  3. 测试结果会在最前面输出:[y]表示测试通过;[x]则表示出错,请仔细查看该行的错误提示或说明。
  4. 运行jar包需要依赖JDK,请确认已安装JDK并设置了系统环境变量。

    运行runMe.bat的结果如下:

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区