云对接平台融合配置指引

一、概述

1、背景简介

IoT平台以及建设在IoT平台之上的业务应用的活力是依赖于各种设备数据的输入，因此连接能力的多样性之于IoT平台来说是至关重要的。

在此基础上，除了常见的直连设备接入、网关设备接入、边缘设备接入之外，物联平台还提供了IoT平台融合能力，用以解决存量存在于其他第三方设备平台的设备能够间接接入物联平台，进行设备数据的上报下发，为物联平台及上层业务应用提供数据基础。

经过第三方设备平台的设备数据必定是格式多样，结构相异，基于一个物联平台的定位，在物联平台需要将这些数据转化为统一的格式结构，供上层业务应用使用，使其专于业务。

2、名词解释

名词	简称	说明
云对接SDK	SDK	设备平台需要集成的，可与物联平台建立连接通讯的开发工具

二、操作步骤说明

1、创建产品

在设备接入前，需要在平台中创建相应的产品，创建产品具体流程可参考《创建产品》。

产品	创建步骤	注意点
产品	填写产品信息	所属平台必须为默认平台

2、证书创建及产品关联

在创建产品之后，需要通过设备中心–>证书管理进行证书的创建。

在证书管理页面点击创建证书，填写证书名称后，将第1步创建的产品关联进此证书中，确保需要上线的设备的所属产品均被此证书关联，完成证书创建。若已创建过可用的证书，则将第一步创建的产品关联进证书中，确保需要上线的设备的所属产品均被此证书关联，完成证书信息更新。

3、创建云对接平台配置

在产品创建及证书创建和产品关联之后，需要跳转至IoT平台融合功能中完成云对接平台配置的创建。具体页面路径如下：设备中心–>IoT平台融合

在IoT平台融合栏目中，点击添加，创建平台类型为云对接平台的融合配置。

关联证书需第2步所创建或增加产品关联的证书，即可完成创建。

4、云对接密钥生成

在云对接配置创建完成之后，点击生成的卡片，进行配置详情–>对接信息中。点击【生成密钥】按钮，物联平台将会根据此配置生成时段内唯一可用的云对接密钥。

注意：

物联平台在密钥生成时供用户下载相应的csv文件，平台在用户下载csv文件之后，不会再次展示该密钥信息，请妥善保存，避免遗忘和泄露；

若密钥遗忘或泄露，您可再次生成云对接密钥，但您相应的云对接SDK配置均需使用新的云对接密钥才可正常与物联平台联动，完成业务。

5、SDK配置

5.1SDK配置说明

配置项	配置说明	获取途径
API访问地址	平台的API接口访问地址	咨询物联平台系统管理员
云对接地址	用于平台设备对接的连接地址	咨询物联平台系统管理员
云对接ID	云对接标识	在第3步中，创建云对接平台融合配置后，配置详情–>对接信息可查看
云对接密钥	云对接授权	在第4步中，生成云对接密钥后，可复制或下载CSV文件获取
证书ID	云对接接入网关证书ID	在第3步中，创建云对接平台融合配置后，配置详情–>证书管理可查看
证书密钥	云对接接入网关证书密钥	在第3步中，创建云对接平台融合配置后，配置详情–>证书管理可查看
是否开启SSL	是否开启SSL	根据物联平台配置，在SDK中配置时候开启SSL进行数据加密传输

5.2 功能限制说明

使用云对接融合配置接入的设备，无法使用物联平台提供的【设备调试】进行调试。
使用云对接融合配置接入的设备，下发设备控制必须通过物联平台、中台设备服务的控制接口

5.3 代码片段示例

5.3.1 SDK初始化

SDK初始化说明：

SDK为单例模式，线程安全；使用时对SDK进行初始化，如无初始化，则无法使用；
SDK初始化成功后，在运行过程中，不需要二次初始化；
SDK初始化失败时，需要检查初始化失败原因，跳过初始化失败则后续的SDK功能无法使用；
SDK在任意情况都可以被调用，使用 XlinkIotSdk.getInstance()可以使用SDK提供的功能；

SDK配置参数：

部分参数可见本文《5.1SDK配置说明》

其他参数：

ServiceInvokeRceiveMode：表示设备下发数据的接收模式，与对接程序的运行架构有关，支持三种方式：
- ServiceInvokeRceiveMode.DEVICE_SHARED：
  
  共享模式，多个对接程序共享一条设备下发数据，共享的对接程序中，ReceiveId需要设置相同。
- ServiceInvokeRceiveMode.EXCLUSIVE：
  
  独占模式，独享一条设备下发数据，ReceiveId唯一，不能冲突。
- ServiceInvokeRceiveMode.FAILOVER：
  
  主备模式，多个对接程序中，只有其中一个接收到设备下发数据，当一个对接程序关闭后，另一个对接程序继续接收设备下发数据；主备模式的ReceiveId需要设置相同。
ReceiveId：对接程序接收ID；主备、共享模式建议设置为connectId；独占模式时，对接程序建议按数字需要生成一个唯一的ID，如某个前缀+数字序号，数字序号可复用；不建议使用UUID；
TokenType：权限类型：
- GATEWAY 网关权限：在网关权限 sdk 只校验 cid 和 connectKey
- APP 应用权限：在网关权限 sdk 只校验 appId 和 appSecret （默认）

代码示例

import cn.xlink.iot.sdk.XlinkIotSdk;
import cn.xlink.iot.sdk.XlinkIotSdkConfig;
import cn.xlink.iot.sdk.entitys.IotDeviceIdentifier;
import cn.xlink.iot.sdk.enums.ServiceInvokeRceiveMode;
import cn.xlink.iot.sdk.inferfaces.IServiceInvokeHandler;
import com.alibaba.fastjson.JSONObject;
 
 
 
public class IotSDKDemo {
 
    public static void main(String[] args) throws Exception {
        /**
         * 对接信息
         */
        String apiHost     = "http://api.xlink.cn";
        String connectHost = "pulsar+ssl://mq-prod.xlink.cn:6651";
        String connectId = "220x*****sd0sa";
        String connectKey = "kz01ka20x***********************************sd0s3lkskaa";
        String appId = "r0x20**wd011";// token类型为应用权限时
        String appSecret = "1akjx002000**s9s00a";// token类型为应用权限时
        String cid = "613868afa8922b6630021636";//token类型为网关权限时
        String cryptoKey = "82d59ed0-5806-46cc-b218-88aa77f06a12";//token类型为网关权限时
         
        String corpId = "234****832323";
 
        /**
         * 构建配置对象
         */
        XlinkIotSdkConfig sdkConfig = XlinkIotSdkConfig.newBuidler()
                .withApiHost(apiHost)
                .withConnectHost(connectHost)
                .withConnectId(connectId)
                .withTokenType(TokenType.GATEWAY) // 默认不填，APP应用权限
                .withCid(cid)
                .withCryptoKey(cryptoKey)
                .withConnectKey(connectKey)
                .withAppId(appId)
                .withAppSecret(appSecret)
                .withCorpId(corpId)
                .withServiceInvokeRceiveMode(ServiceInvokeRceiveMode.DEVICE_SHARED)
                .withReceiveId(connectId)
                .withSsl(true)// 默认不填为false，是否开启ssl
                .withServiceInvokeHandler(new IServiceInvokeHandler() {
                    @Override
                    public void serviceInvoke(IotDeviceIdentifier iotDeviceIdentifier, String messageId, String serviceName, JSONObject jsonObject) {
                        //收到服务下发控制
                    }
                }).build();
 
        /**
         * SDK 初始化
         */
        XlinkIotSdk.getInstance().init(sdkConfig);
 
    }
 
}

5.3.2 设备注册

设备注册有两种方式：

第一种：在物联平台通过【设备注册】功能进行注册设备；
第二种：通过SDK注册设备；

代码示例

import cn.xlink.iot.sdk.XlinkIotSdk;
import cn.xlink.iot.sdk.XlinkIotSdkConfig;
import cn.xlink.iot.sdk.entitys.IotDeviceIdentifier;
import cn.xlink.iot.sdk.entitys.RegisterDevice;
import cn.xlink.iot.sdk.enums.ServiceInvokeRceiveMode;
import cn.xlink.iot.sdk.inferfaces.IServiceInvokeHandler;
import com.alibaba.fastjson.JSONObject;
 
 
 
public class IotSDKDemo {
 
    public static void main(String[] args) throws Exception {
        //SDK初始化
        ....
        ....
         
 
        RegisterDevice registerDevice = new RegisterDevice();
        registerDevice.setProductId("...");
        registerDevice.setMac("...");
        registerDevice.setName("...");
        registerDevice.setSn("...");
 
        /**
         * 同步注册
         */
        XlinkIotSdk.getInstance().registerDevice(registerDevice).get();
 
        /**
         * 异步注册
         */
        XlinkIotSdk.getInstance().registerDevice(registerDevice).whenComplete((unused, throwable) -> {
           // ...
        });
         
    }
 
}

5.3.3 设备在线状态

支持异步、同步上报设备状态;
支持基于ProductId+Mac或者基于设备ID进行上报状态;

注意：上报设备在线状态时，必须在平台已经注册设备。

代码示例

import cn.xlink.iot.sdk.XlinkIotSdk;
import cn.xlink.iot.sdk.XlinkIotSdkConfig;
import cn.xlink.iot.sdk.entitys.IotDeviceIdentifier;
import cn.xlink.iot.sdk.enums.ServiceInvokeRceiveMode;
import cn.xlink.iot.sdk.inferfaces.IServiceInvokeHandler;
import com.alibaba.fastjson.JSONObject;
 
 
 
public class IotSDKDemo {
 
    public static void main(String[] args) throws Exception {
        //SDK初始化
        ....
        ....
 
 
        String productId = "16020******20w0q";
        String mac = "10020011";
        int deviceId = 100000042;
 
        /**
         * 同步
         */
        XlinkIotSdk.getInstance().online(IotDeviceIdentifier.build(productId, mac)).get();
 
        /**
         * 异步
         */
        XlinkIotSdk.getInstance().online(IotDeviceIdentifier.build(productId, mac)).whenComplete((unused, throwable) -> {
            //TODO
        });
 
    }
 
}

5.3.4 设备上报属性/事件

支持异步、同步上报设备属性/事件
支持基于ProductId+Mac或者基于设备ID进行上报状态

注意：上报设备属性/实践，必须在平台已经注册设备。

代码示例

import cn.xlink.iot.sdk.XlinkIotSdk;
import cn.xlink.iot.sdk.XlinkIotSdkConfig;
import cn.xlink.iot.sdk.entitys.IotDeviceIdentifier;
import cn.xlink.iot.sdk.enums.ServiceInvokeRceiveMode;
import cn.xlink.iot.sdk.inferfaces.IServiceInvokeHandler;
import com.alibaba.fastjson.JSONObject;
 
 
 
public class IotSDKDemo {
 
    public static void main(String[] args) throws Exception {
        //SDK初始化
        ....
        ....
 
        String productId = "16020******20w0q";
        String mac = "10020011";
        int deviceId = 100000042;
 
 
        /**
         * 同步发送
         */
        XlinkIotSdk.getInstance().reportAttribute(IotDeviceIdentifier.build(productId, mac),  new JSONObject() {{
            put("state", "open"); //属性字段
            put("color", "red");//属性字段
        }}).get();
 
 
        /**
         * 异步发送
         */
        XlinkIotSdk.getInstance().reportAttribute(IotDeviceIdentifier.build(productId, mac),  new JSONObject() {{
            put("state", "open"); //属性字段
            put("color", "red");//属性字段
        }}).whenComplete((unused, throwable) -> {
           //..
        });
 
 
        /**
         * 同步发送
         */
        XlinkIotSdk.getInstance().reportEvent(IotDeviceIdentifier.build(productId, mac), "alert",  new JSONObject() {{
            put("state", "alert"); //事件字段
        }}).get();
 
 
        /**
         * 异步发送
         */
        XlinkIotSdk.getInstance().reportEvent(IotDeviceIdentifier.build(productId, mac), "alert",  new JSONObject() {{
            put("state", "alert"); //事件字段
        }}).whenComplete((unused, throwable) -> {
            //..
        });
    }
 
}

5.3.5 设备服务调用以及回复

设备服务调用回调在SDK初始化时，指定一个接口为IServiceInvokeHandler的实现类；
当有设备服务下发时，会调用接口IServiceInvokeHandler的serviceInvoke方法触发；

代码示例

import cn.xlink.iot.sdk.XlinkIotSdk;
import cn.xlink.iot.sdk.XlinkIotSdkConfig;
import cn.xlink.iot.sdk.entitys.IotDeviceIdentifier;
import cn.xlink.iot.sdk.enums.ServiceInvokeRceiveMode;
import cn.xlink.iot.sdk.inferfaces.IServiceInvokeHandler;
import com.alibaba.fastjson.JSONObject;
 
 
 
public class IotSDKDemo {
 
    public static void main(String[] args) throws Exception {
        /**
         * 对接信息
         */
        String apiHost     = "http://api.xlink.cn";
        String connectHost = "pulsar+ssl://mq-prod.xlink.cn:6651";
        String connectId = "220x*****sd0sa";
        String connectKey = "kz01ka20x***********************************sd0s3lkskaa";
        String certId = "r0x20**wd011";
        String certKey = "1akjx002000**s9s00a";
 
        /**
         * 构建配置对象
         */
        XlinkIotSdkConfig sdkConfig = XlinkIotSdkConfig.newBuidler()
                .withApiHost(apiHost)
                .withConnectHost(connectHost)
                .withConnectId(connectId)
                .withCertKey(connectKey)
                .withCertId(certId)
                .withCertKey(certKey)
                .withServiceInvokeRceiveMode(ServiceInvokeRceiveMode.DEVICE_SHARED)
                .withReceiveId(connectId)
                .withServiceInvokeHandler(new IServiceInvokeHandler() {
                    @Override
                    public void serviceInvoke(IotDeviceIdentifier iotDeviceIdentifier, String messageId, String serviceName, JSONObject jsonObject) {
                        //收到服务下发控制
                        //...处理逻辑
                        //回复服务下发
                        XlinkIotSdk.getInstance().replyServiceInvokeSuccess(iotDeviceIdentifier, messageId, serviceName, new JSONObject() {{
                            put("...", ".."); //服务输出字段
                        }});
                    }
                }).build();
 
        /**
         * SDK 初始化
         */
        XlinkIotSdk.getInstance().init(sdkConfig);
 
    }
 
}

6、获取SDK

<dependency>
<groupId>cn.xlink</groupId>
<artifactId>xlink-iot-sdk</artifactId>
<version>4.0.1-pg</version>
</dependency>

7、设备上线验证

在企业管理台和云对接平台配置完成之后，使设备通电通网，并上报设备数据后，查看企业管理台中映射的产品的设备列表，并且查看设备详情中的实时状态数据与物理设备数据的一致性。

若产品中自动成功注册了云对接平台中相应的上线设备，并且设备数据正常，则实施流程结束；

若产品中没有注册云对接平台中相应的上线设备，或者上线后设备数据不正常，则需要检查以下几个方面：

云对接融合配置中证书是都已关联此次上线设备的所属产品；
云对接SDK的配置项正确性；

确认无误后，设备仍不能上线或设备数据不正常，请联系系统管理员进行处理。

三、常见问题

待补充。

四、修订记录

修订时间	编写人	修订内容
2022-12-14	黄奕坚	起稿

上次更新：2024-05-09