本文介绍泛化协议SDK的一些进阶能力的用法,包括自定义配置文件路径、配置动态创建网桥设备、调用泛化协议SDK中封装的数据上报接口上报属性、事件和标签。

自定义配置管理

默认情况下,网桥的配置文件和设备证书的映射关系配置文件,都是从固定路径的固定文件名(分别是application.confdevices.conf)中读取的。泛化协议SDK提供了自定义配置管理的能力,您只需要在调用bootstrap方法之前,先调用ConfigFactory.init方法,自定义配置文件的路径,也可以自定义实例实现对应的接口。

自定义配置代码示例:

//Define config
//You can specify the location path of config files 
//or you can create an instance and implement the corresponding interface
//Config.init() must be called before bridgeBootstrap.bootstrap()
ConfigFactory.init(
    ConfigFactory.getBridgeConfigManager("application-self-define.conf"),
    selfDefineDeviceConfigManager);
bridgeBootstrap.bootstrap();

private static DeviceConfigManager selfDefineDeviceConfigManager = new DeviceConfigManager() {
    @Override
    public DeviceIdentity getDeviceIdentity(String originalIdentity) {
        //Suppose you dynamically get deviceInfo in other ways
        return devicesMap.get(originalIdentity);
    }

    @Override
    public String getOriginalIdentity(String productKey, String deviceName) {
        //you can ignore this
        return null;
    }
};

动态创建网桥设备

当您需要在大量的服务器上部署网桥应用,如果为每一个网桥服务器指定不同的网桥设备信息会比较繁琐。您可以配置网桥信息文件application.conf动态创建网桥设备。您需在配置文件中,传入参数productKeypopClientProfile,泛化协议SDK将调用物联网平台开放API,以服务器MAC地址作为设备名称,新创建一个网桥设备。

说明
  • 采用动态创建网桥设备方法,仅需要修改网桥配置文件,调用代码与基础用法一致。
  • 网桥配置文件中,如果已经指定了网桥设备信息,不会再动态创建设备。仅当配置文件中deviceNamedeviceSecret配置为空,且popClientprofile所有配置齐全的情况下,泛化协议SDK才会尝试调用物联网平台API,以服务器MAC地址作为设备名称动态创建设备。如果当前MAC地址已经创建过设备,则会直接使用这个设备作为网桥设备。
  • 如果采用这种方式配置网桥,不建议您使用生产环境的配置直接在本地机器上调试。因为在多个本地PC上调试程序,每次都会将当前机器的MAC地址注册为网桥,并将设备信息配置文件devices.conf中的所有设备与该网桥关联。建议在调试阶段使用专门用于测试的设备,以免干扰生产环境。
表 1. 配置参数说明
参数 是否必需 说明
productKey 网桥所属产品的 ProductKey。
http2Endpoint

HTTP2网关服务地址。 网桥和云端通过HTTP2协议建立长连接通道。 HTTP2网关服务地址的结构为:${productKey}.iot-as-http2.${RegionId}.aliyuncs.com:443

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

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

如,某网桥设备的productKey为alabcabc123,地域为上海,则HTTP2网关服务地址是 alabcabc123.iot-as-http2.cn-shanghai.aliyuncs.com:443

authEndpoint

设备认证服务地址。 设备认证服务地址结构为:https://iot-auth.${RegionId}.aliyuncs.com/auth/bridge

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

如,地域为上海,则认证服务地址就是 https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge

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

具体参数配置见下表popClientProfile。

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

请登录阿里云控制台,单击您的账号头像,进入AccessKey管理中,创建或查看AccessKey。

accessSecret 您的阿里云账号的AccessKey Secret。
name 将要创建网桥设备的物联网平台服务地域,即productKey值所代表的产品所属的地域。

地域的表达方法,请参见通用参考中地域和可用区文档。

region 将要创建网桥设备的物联网平台服务地域ID,即productKey值所代表的产品所属的地域。

表达方法同name

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

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

如上海节点的 endpoint 为:iot.cn-shanghai.aliyuncs.com

动态创建网桥设备配置示例:

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

# Gateway device info
# You can also specify productKey only, and dynamic register deviceName & deviceSecret in runtime
productKey = ${YourProductKey}

# If you dynamic register gateway device using your mac address, you have to specify 'popClientProfile'
# otherwise you can ignore it
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();
//report property
//Property 'testProp' is defined in IoT Platform Web Console
String requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.reportProperty(requestId, originalIdentity, "testProp", random.nextInt(100));

//fire event
//Event 'testEvent' is defined in IoT Platform Web Console
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);

//update device tag
//'testDeviceTag' is a tag key defined in IoT Platform Web Console
requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.updateDeviceTag(requestId, originalIdentity, "testDeviceTag", String.valueOf(random.nextInt(1000)));

以上示例中,接口调用的参数说明:

参数 说明
requestId 请求消息ID。
originalIdentity 设备的原始身份标识符。
testProp 属性的identifier。本示例的前提条件是:在物联网平台控制台上为产品定义功能时,定义了一个identifier为testProp属性。本示例代码为上报属性testProp的值。
random.nextInt(100) 上报的属性值。属性值的取值范围也在定义属性时定义。在本示例中,使用random.nextInt(100)表示取小于100的整形随机值。
testEvent 事件的identifier。本示例的前提条件是:在物联网平台控制台为产品定义功能时,定义了一个identifier为testEvent的事件。本示例代码为上报事件testEvent。
ThingEventTypes.INFO 事件类型。ThingEventTypes参数表示事件类型,INFO表示事件类型取值为INFO(信息)。

本示例的前提条件是:在物联网平台控制台上定义事件testEvent时,选择的事件类型为信息(即INFO)。

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