Java SDK使用指南（联通用户专用）

开发环境要求

SDK包为纯JAVA的JAR包，在使用上没有特殊限制，JDK在1.8及以上版本即可。

导入Demo工程

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

   

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

   

4. 如果开发者无法从maven仓库下载Demo工程依赖的jar包，可以从Demo文件的components文件夹下手动导入工程依赖包。

   

初始化及证书配置

新建一个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实例后才能调用其他业务接口。以如下几个接口为例说明如何调用业务接口。

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

鉴权

1
2
3
4
5
6
7
8
9

//得到NorthApiClient实例后，再使用northApiClient得到鉴权类实例
Authentication authentication = new Authentication(northApiClient);

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

//从返回的结构体authOutDTO中获取需要的参数，如accessToken，不同接口的token是通用的，只用获取一次，token有效期为1小时。在即将到1小时前，可调用刷新鉴权接口重新获取token

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();

回调接口实现及证书制作

回调接口实现

1
2
3
4
5

@Override
public void handleDeviceAdded(NotifyDeviceAddedDTO body) {
    System.out.println("deviceAdded ==> " + body);
    //TODO deal with deviceAdded notification
}

接收到平台推送的消息后，开发者需要根据业务进行处理，但不建议进行复杂计算、I/O操作或者可能长时间等待的动作，可以先写数据库，应用进入相应界面或者刷新界面再从数据库取数据并进行数据处理。

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 {jdk的bin路径}

   

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

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

   

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

   注：平台的测试根证书ca.pem可以在JAVA SDK包的cert目录下找到。

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

   

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

   

   将物联网平台提供的根证书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”、“所属行业”、“设备类型”、“接入应用层协议类型”等产品信息，点击“创建”。然后点击“+新建服务”（根据设备功能添加属性和命令）最后点击“保存”。

• 修改设备信息接口使用到的字段值如“设备类型”、“厂商名”、“厂商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的结果如下：