本文介绍云云对接SDK中进阶功能的使用,包括自定义配置文件路径、配置动态创建网桥设备、调用SDK中封装的数据上报接口上报属性、事件和标签。

自定义配置管理

默认情况下,网桥的配置文件和设备证书的映射关系配置文件,都是从固定路径的固定文件(分别是application.confdevices.conf)中读取的。

云云对接SDK提供自定义配置能力,您只需在调用bootstrap方法前,先调用ConfigFactory.init方法,自定义配置文件的路径,自定义实例实现对应的接口。

代码示例:

ConfigFactory.init(
    ConfigFactory.getBridgeConfigManager("application-self-define.conf"),
    selfDefineDeviceConfigManager);
bridgeBootstrap.bootstrap();

private static DeviceConfigManager selfDefineDeviceConfigManager = new DeviceConfigManager() {
    @Override
    public DeviceIdentity getDeviceIdentity(String originalIdentity) {
        return devicesMap.get(originalIdentity);
    }

    @Override
    public String getOriginalIdentity(String productKey, String deviceName) {
        return null;
    }
};

动态创建网桥设备

如果在大量的服务器上部署网桥应用,为每一个网桥服务器指定不同的网桥设备信息会比较繁琐。您可配置网桥信息文件application.conf,动态创建网桥设备。

您需在配置文件中,传入参数productKeypopClientProfile,云云对接SDK将调用物联网平台开放的API,以服务器MAC地址作为设备名称,创建一个网桥设备。

说明
  • 动态创建网桥设备,仅需修改网桥配置文件,调用代码与基础用法一致。
  • popClientprofile的所有参数必须配置完整。如果当前MAC地址为已有设备名称,会直接使用该设备作为网桥设备。
  • 参数deviceNamedeviceSecret值必须为空,如果已指定网桥设备信息,不会再动态创建设备。
  • 建议使用专用的调测设备调试程序,不要直接在本地机器上调试,以免影响正式的生产环境。

    在多个本地PC上调试程序,每次都会将当前机器的MAC地址注册为网桥,并将devices.conf文件中的所有设备与该网桥关联。

表 1. 配置参数说明
参数 是否必需 说明
productKey 网桥所属产品的ProductKey。
subDeviceConnectMode 网桥挂载设备模式:
  • 传入该参数,且取值为3,则为大型网桥,单网桥下最大支持挂载500,000个设备。
  • 不传入该参数,则为小型网桥,单网桥下最大支持挂载1,500个设备。
大型网桥、小型网桥的挂载设备下线策略不同,请参见#d7e386
http2Endpoint HTTP2网关服务地址。网桥和云端通过HTTP2协议建立长连接通道。

地址结构:

  • 公共实例:https://${productKey}.iot-as-http2.${RegionId}.aliyuncs.com:443

    其中,变量${productKey}需替换成您的网桥所属产品的ProductKey。

    变量${RegionId}需替换成您的服务所在地域代码。RegionId的表达方法,请参见地域和可用区

    例如:某用户的网桥设备的productKey为a1abcab****,地域为上海,地址为https://a1abcab****.iot-as-http2.cn-shanghai.aliyuncs.com:443

  • 企业版实例:https://${IotInstanceId}.http2.iothub.aliyuncs.com:443

    其中,变量${IotInstanceId}需替换成实例ID。

    例如:某用户的企业版实例的实例ID为iot-cn-g06kwb****,地址为https://iot-cn-g06kwb****.http2.iothub.aliyuncs.com:443

authEndpoint 设备认证服务地址。

地址结构:

  • 公共实例:https://iot-auth.${RegionId}.aliyuncs.com/auth/bridge

    其中,变量${RegionId}需替换成您的服务所在地域代码。RegionId的表达方法,请参见地域和可用区

    例如:地域为上海,则地址为https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge

  • 企业版实例:https://${IotInstanceId}.auth.iothub.aliyuncs.com/auth/bridge

    其中,变量${IotInstanceId}需替换成实例ID。

    例如:某用户的企业版实例的实例ID为iot-cn-g06kwb****,则地址为 https://iot-cn-g06kwb****.auth.iothub.aliyuncs.com/auth/bridge

popClientProfile 配置此参数,云云对接SDK将调用阿里云端开放接口自动创建一个网桥设备。

具体参数配置见下表popClientProfile。

表 2. popClientProfile
参数 是否必需 描述
accessKey 您的阿里云账号的AccessKey ID。

物联网平台控制台,鼠标移动到您的账号头像上,然后单击AccessKey管理,创建或查看AccessKey。

accessSecret 您的阿里云账号的AccessKey Secret。
name 将要创建网桥设备的所在地域ID。

地域的表达方法,请参见地域和可用区

region
product 产品名称,固定为Iot。
endpoint 调用指定地域API的节点地址。结构为iot.${RegionId}.aliyuncs.com

其中,变量${RegionId}需替换成您的服务所在地域代码。RegionId的表达方法,请参见地域和可用区

例如:上海地域的endpoint为iot.cn-shanghai.aliyuncs.com

以公共实例为例,动态创建小型网桥设备。

# 服务地址
http2Endpoint = "https://${YourProductKey}.iot-as-http2.cn-shanghai.aliyuncs.com:443"
authEndpoint = "https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge"

# 网桥设备信息
productKey = ${YourProductKey}

popClientProfile = {
    accessKey = ${YourAliyunAccessKey}
    accessSecret = ${YourAliyunAccessSecret}
    name = cn-shanghai
    region = cn-shanghai
    product = Iot
    endpoint = iot.cn-shanghai.aliyuncs.com
}

调用物模型数据上报接口

云云对接SDK中暂不提供服务调用和属性设置接口,仅封装部分数据上报接口,包括属性上报接口 reportProperty、事件上报接口fireEvent和更新设备标签接口updateDeviceTag。设备可通过以上接口向物联网平台上报相应消息。

说明
  • 调用reportPropertyfireEvent上报属性值和事件前,您需先在物联网平台控制台设备所属产品的产品详情页的功能定义页签下,定义属性和事件。请参见单个添加物模型
  • 调用updateDeviceTag接口上报设备标签时,如果您已在物联网平台控制台设备对应的设备详情页,添加了该标签,则更新标签值(value)。否则,新建标签。

接口调用示例:

TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
//上报属性。
//已定义testProp属性。
String requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.reportProperty(requestId, originalIdentity, "testProp", random.nextInt(100));

//上报事件。
//已定义testEvent事件。
requestId = String.valueOf(random.nextInt(1000));
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("testEventParam", 123);
tslUplinkHandler.fireEvent(originalIdentity, "testEvent", ThingEventTypes.INFO, params);

//上报设备标签。
//已定义设备标签key为testDeviceTag。
requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.updateDeviceTag(requestId, originalIdentity, "testDeviceTag", String.valueOf(random.nextInt(1000)));

以上示例中参数说明如下。

参数 说明
requestId 请求消息ID。
originalIdentity 设备的原始身份标识符。
testProp 属性的identifier。本示例的产品已定义功能属性标识符为testProp。本示例上报了该属性的值。
random.nextInt(100) 上报的属性值。定义属性时,可设置其取值范围。在本示例中,使用random.nextInt(100)表示取小于100的整形随机值。
testEvent 事件的identifier。本示例的产品已定义功能事件标识符为testEvent。本示例上报了该事件。
ThingEventTypes.INFO 事件类型。ThingEventTypes表示事件类型,INFO表示事件类型值为INFO(信息)。

本示例产品定义事件testEvent时,选择的事件类型为信息(INFO)。

如果事件类型定义为故障,则该参数为ThingEventTypes.ERROR

params 事件的输出参数。事件输出参数的identifier、数据类型、取值范围等已在定义事件时定义。本示例中,上报事件的出参identifiertestEventParam,参数值是123。
testDeviceTag 设备标签键(key),String类型。本示例中为testDeviceTag。 实际使用时,请根据设备标签键规范和您的需求设置。更多信息,请参见设备标签
String.valueOf(random.nextInt(1000)) 设备标签值(value),String类型。本示例中,用String.valueOf(random.nextInt(1000))表示取一个小于1000的随机值。实际使用时,请根据设备标签值规范和您的需求设置,请参见设备标签