华为云用户手册

开发规范 开发工具版本要求： IntelliJ IDEA：2018.3.5或以上版本。 Eclipse：3.6.0或以上版本。 Visual Studio：2019 version 16.8.4或以上版本。 开发语言环境版本要求： Java：1.8.111或以上版本的Java Development Kit。 Python：2.7或3.X版本的Python。 Go：1.14及以上版本的Go。 C#：6.0及以上版本的.NET。 客户端版本使用建议： ROMA Connect的Kafka版本 Kafka客户端建议版本 1.1.0 Java：1.1.0及以上版本 Python：2.0.1及以上版本 Go：1.8.2及以上版本 C#：1.5.2及以上版本 2.7 Java：2.7.2及以上版本 Python：2.0.1及以上版本 Go：1.8.2及以上版本 C#：1.5.2及以上版本 客户端开发和配置建议： 请参见客户端使用建议和客户端参数配置建议。 父主题： 开发说明

消息生产与消费的幂等传递 ROMA Connect设计了一系列可靠性保障措施，确保消息不丢失。例如使用消息同步存储机制防止系统与服务器层面的异常重启或者掉电，使用消息确认（ACK）机制解决消息传输过程中遇到的异常。 考虑到网络异常等极端情况，用户除了做好消息生产与消费的确认，还需要配合ROMA Connect完成消息发送与消费的重复传输设计。 当无法确认消息是否已发送成功，生产者需要将消息重复发送给ROMA Connect。 当重复收到已处理过的消息，消费者需要告知ROMA Connect消费成功且保证不重复处理。

消息可以批量生产和消费 为提高消息发送和消息消费效率，推荐使用批量消息发送和消费。通常，默认消息消费为批量消费，而消息发送尽可能采用批量发送，可以有效减少API调用次数。 如下面两张示意图对比所示，消息批量生产与消费，可以减少API调用次数，节约资源。 图1 消息批量生产与消费 批量发送消息时，单次不能超过10条消息，总大小不能超过512KB。 批量生产（发送）消息可以灵活使用，在消息并发多的时候，批量发送，并发少时，单条发送。这样能够在减少调用次数的同时保证消息发送的实时性。 图2 消息逐条生产与消费 此外，批量消费消息时，消费者应按照接收的顺序对消息进行处理、确认，当对某一条消息处理失败时，不再需要继续处理本批消息中的后续消息，直接对已正确处理的消息进行确认即可。

不支持zstd压缩类型 Kafka在2.1.0版本新增了zstd压缩类型，而1.1.0版本的Kafka不支持zstd压缩类型。 配置文件： src/main/resources/application.yml 配置项： spring: kafka: producer: compression-type: xxx 使用限制： “compression-type”的值不能设置为“zstd”。

重视消息生产与消费的确认过程 消息生产 生产消息后，生产者需要根据ROMA Connect的返回信息确认消息是否发送成功，如果返回失败需要重新发送。 每次生产消息，生产者都需要等待消息发送API的应答信号，以确认消息是否成功发送。在消息传递过程中，如果发生异常，生产者没有接收到发送成功的信号，生产者自己决策是否需要重复发送消息。如果接收到发送成功的信号，则表明该消息已经被ROMA Connect可靠存储。 消息消费 消息消费时，消费者需要确认消息是否已被成功消费。 生产的消息被依次存储在ROMA Connect的存储介质中。消费时依次获取ROMA Connect中存储的消息。消费者获取消息后，进行消费并记录消费成功或失败的状态，并将消费状态提交到ROMA Connect，由ROMA Connect决定消费下一批消息或回滚重新消费消息。 在消费过程中，如果出现异常，没有提交消费确认，该批消息会在后续的消费请求中再次被获取。

概述 spring-kafka兼容开源Kafka客户端，其与开源Kafka客户端的版本对应关系可参见Spring官网。spring-kafka兼容的Kafka客户端版本主要为2.x.x版本，而ROMA Connect消息集成的Kafka服务端版本为1.1.0、2.7版本。因此在Spring Boot项目工程中使用spring-kafka连接ROMA Connect时，请确保客户端与服务端的Kafka版本一致。 若spring-kafka连接的ROMA Connect实例为Kafka 1.1.0版本时，大部分的功能可以正常使用，仅少数新增功能不支持。经排查验证，以下为不支持的功能，除此以外的其他功能暂未发现问题。如果在使用过程中遇到其他问题，请提工单联系技术支持。

不支持消费者组静态成员功能 Kafka客户端在2.3版本新增了Consumer参数“group.instance.id”，设置了该ID的消费者被视为一个静态成员。 配置文件： src/main/resources/application.yml 配置项： spring: kafka: consumer: properties: group.instance.id: xxx 使用限制： 不能添加“group.instance.id”参数配置。

前提条件 准备装有1.8及以上版本JDK的Linux服务器。 IntelliJ IDEA版本为：2018.3.5或以上版本，Eclipse版本为：3.6.0或以上版本。 通过Demo（sha256:34c9bc8d99eba4ed193603019ce2b69afa3ed760a452231ece3c89fd7dd74da1）获取RealtimeConnector.rar包。 用户程序向MQS写入消息的TPS不能超过6000/s。

调用API（Node.js）示例 在工程中引入signer.js。 var signer = require('./signer')var http = require('http') 生成一个新的Signer，输入API所授权凭据的Key和Secret，可参考获取API的调用信息获取。 var sig = new signer.Signer()// Directly writing AK/SK in code is risky. For security, encrypt your AK/SK and store them in the configuration file or environment variables. // In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, set environment variables HUAWEICLOUD_SDK_AK and HUAWEICLOUD_SDK_SK. sig.Key = process.env.HUAWEICLOUD_SDK_AKsig.Secret = process.env.HUAWEICLOUD_SDK_SK 生成一个Request对象，指定方法名、请求url和body，可参考获取API的调用信息获取。 var r = new signer.HttpRequest("POST", "c967a237-cd6c-470e-906f-a8655461897e.apigw.exampleRegion.com/app1?a=1");r.body = '{"a":1}' 给请求添加x-stage头，内容为环境名。如有需要，添加需要签名的其他头域。 r.headers = { "x-stage":"RELEASE" } 进行签名，执行此函数会生成请求参数，用于创建http(s)请求，请求参数中添加了用于签名的X-Sdk-Date头和Authorization头。 var opts = sig.Sign(r) 访问API，查看访问结果。如果使用https访问，则将“http.request”改为“https.request”。 var req=http.request(opts, function(res){ console.log(res.statusCode) res.on("data",function(chunk){console.log(chunk.toString())})})req.on("error",function(err){console.log(err.message)})req.write(r.body)req.end()

准备开发环境 安装开发工具 请根据所使用语言选择适合的开发工具。 安装2018.3.5或以上版本的IntelliJ IDEA，安装包请至IntelliJ IDEA官方网站下载。 安装2019 version 16.8.4及以上版本的Visual Studio，安装包请至Visual Studio官方网站下载。 安装开发语言环境 Java：安装1.8.111或以上版本的Java Development Kit，安装包请至Oracle官方下载页面下载。 Python：安装2.7或3.X版本的Python安装包，安装包请至Python官方下载页面下载。

前提条件 已获取API的调用信息，具体请参见开发准备。 已安装开发工具和JavaScript开发语言环境，具体请参见开发准备。 Nodejs安装后，在命令行中，用npm安装“moment”和“moment-timezone”模块。 npm install moment --savenpm install moment-timezone --save 已在IntelliJ IDEA中安装NodeJS插件，如果未安装，请按照图1所示安装。 图1 安装NodeJS插件 浏览器版本为Chrome 89.0或以上版本。

响应消息 响应参数 参数 类型 说明 handler String 消息handler。 message Object 消息的内容。 表2 message参数 参数 类型 说明 content String 消息体的内容。Base64加密密文。 响应示例 [ { "handler": "NCMxMDAjMTgjMA==", "message": { "content": "ImhlbGxvIGh1YXdlaWNsb3VkLTIi" } }]

URI GET /v1/topic/{topic_name}/group/{group_name}/messages?ack_wait={ack_wait}& time_wait={time_wait}&max_msgs={max_msgs} 表1 参数说明 参数 类型 必选 说明 topic_name String 是 主题名称。 group_name String 是 消费组名称。长度不超过249位的字符串，包含a~z，A~Z，0~9、中划线（-）和下划线（_）。 ack_wait Integer 否 提交确认消费的超时时间，客户端需要在该时间内提交消费确认，如果超过指定时间，没有确认消费，系统会报消息确认超时或handler无效，则默认为消费失败。取值范围：1~300s。默认值：15s time_wait Integer 否 设定队列可消费的消息为0时的读取消息等待时间。 如果在等待时间内有新的消息，则立即返回消费结果，如果等待时间内没有新的消息，则到等待时间后返回消费结果。取值范围：1~30s。 默认值：3s max_msgs Integer 否 获取可消费的消息的条数。取值范围：1~10。默认值：10 max_bytes Integer 否 每次消费的消息总负载最大值。取值范围：1~ 2097152。默认值：524288。

方法详情 public static String json2Xml(String json) json转xml 输入参数 json：json格式的字符串 返回信息 返回xml格式字符串 public static String xml2Json(String xml) xml转json 输入参数 xml：xml格式的字符串 返回信息 返回json格式字符串 public static String json2XmlWithoutType(String json) json转xml 输入参数 json：json格式的字符串 返回信息 返回xml格式字符串 public static HashMap jsonToMap(String json) json转map 输入参数 json：json格式的字符串 返回信息 返回map格式字符串

构造器详情 public RabbitMqConfig(ConnectionConfig connectionConfig, QueueConfig queueConfig, ExchangeConfig exchangeConfig) 构造一个RabbitMQ客户端配置。 参数： connectionConfig表示客户端连接配置。 queueConfig表示队列配置。 exchangeConfig表示交换器配置。

方法列表 返回类型 方法和说明 static String json2Xml(String json) json转xml static String xml2Json(String xml) xml转json static String json2XmlWithoutType(String json) json转xml static HashMap jsonToMap(String json) json转map

示例 { "devices": [{ "deviceId": "D68NZxB4", "services": [{ "data": { "key": "value" }, "eventTime": "20191023T173625Z", "serviceId": "serviceName" }] }]}

数据API中的执行语句说明 数据API调用存储过程时，参数可通过后端服务请求的Headers、Parameters或者Body传递，参数名的语法为：{参数名}.{数据类型}.{传输类型}。 数据类型包括String和int。 传输类型指入参或出参声明，入参使用in，出参使用out。 数据API中调用存储过程的执行语句示例： call sb_test(${nname.String.in},${nsal.int.out}) 该脚本示例中，nname为字符串类型的入参，参数名为nname.String.in ，value则是你要查询的参数值。nsal为数值类型的出参，参数名为nsal.int.out，由于格式限定，出参的value也需要填写，可填写符合数据类型的任意值，不影响输出结果。 数据API中对存储过程的调用，用String和int来区分字符串和数值，无需加单引号，这一点和SQL要求不一样。 在后端服务的Headers、Parameters或者Body中定义的参数名不能相同，否则将被覆盖。 Body传递参数示例： 后端服务请求的Body内容 { "nname.String.in": "zhang", "nsal": 0} 响应结果 { "test": [ 5000 ]} Parameters传递参数示例： 后端服务请求的Parameters内容 https://example.com?nname.String.in=zhang&nsal=0 响应结果 { "test": [ 5000 ]}

准备开发环境 安装开发工具 请根据所使用语言选择适合的开发工具。 安装2018.3.5或以上版本的IntelliJ IDEA，安装包请至IntelliJ IDEA官方网站下载。 安装3.0.3及以上版本Apache Maven，安装包请至Maven官方下载页面下载。 安装2019 version 16.8.4及以上版本的Visual Studio，安装包请至Visual Studio官方网站下载。 安装开发语言环境 Java：安装1.8.111或以上版本的Java Development Kit，安装包请至Oracle官方下载页面下载。 Python：安装2.7或3.X版本的Python，安装包请至Python官方下载页面下载。 Go：安装1.14及以上版本的Go，安装包请至Go官方下载页面下载。 C#：安装6.0及以上版本的.NET，安装包请至.NET官方下载页面下载。

数据源说明 假设数据库里面有一张表，表结构如下建表语句所示： create table sp_test(id number,name varchar2(50),sal number); 往表中并插入数据，数据集如下表所示： 表1 sp_test表数据集 ID NAME SAL 1 ZHANG 5000 2 LI 6000 3 ZHAO 7000 4 WANG 8000 在Oracle数据库中调用存储过程，根据name查询sal的值。 create or replace procedure APICTEST.sb_test(nname in varchar, nsal out number) asbeginselect sal into nsal from sp_test where name = nname;end;

开发规范 开发工具版本要求： IntelliJ IDEA：2018.3.5或以上版本。 Eclipse：3.6.0或以上版本。 开发语言环境版本要求： 1.8.111或以上版本的Java Development Kit。 设备开发要求： 通过MQTT协议接入设备时，当前仅支持MQTT协议中的QoS0和QoS1。 为防止因网络不稳定或实例升级等原因导致设备连接中断，建议在设备开发过程中增加自动重连机制。如果使用ROMA Connect提供的设备demo，则默认已开启重连机制。如果使用开源MQTT客户端，则需要根据开源代码配置重连机制。开启自动重连后，如果连接丢失，客户端会一直自动重连服务器，直到连接成功为止。 父主题： 开发说明

方法详情 public static String JSON2XML(String json, boolean returnFormat) json转xml 输入参数 json：json格式的字符串 returnFormat：返回格式 返回信息 返回xml格式字符串 public static String XML2JSON(String xml) xml转json 输入参数 xml：xml格式的字符串 返回信息 返回xml格式字符串

方法列表 返回类型 方法和说明 static String toString(byte[] bytes, String encoding) 将字节数组转换为字符串 static String toString(byte[] bytes) 将字节数组转换成UTF-8编码字符串 static String toHexString(byte[] data) 将字节数组转成十六进制小写字符串 static byte[] hexToByteArray(String hex) 将十六进制字符串转换成字节数组

方法详情 public static String toString(byte[] bytes, String encoding) 将字节数组转换为字符串 输入参数 bytes：需要转换的字节数组 encoding：编码 返回信息 返回转换后的字符串 public static String toString(byte[] bytes) 将字节数组转换成UTF-8编码字符串 输入参数 bytes：需要转换的字节数组 返回信息 返回转换后的字符串 public static String toHexString(byte[] data) 将字节数组转成十六进制小写字符串 输入参数 data：需要转换的字节数组 返回信息 返回转换后的十六进制字符串 public static byte[] hexToByteArray(String hex) 将十六进制字符串转换成字节数组 输入参数 hex：需要转换的十六进制字符串 返回信息 返回转换后的字节数组

示例 { "data": [{ "deviceInfo": { "manufacturerId": "Test_n", "name": "n-device", "model": "A_n", "nodeId": "n-device", "deviceId": "D59eGSxy" }, "statusCode": 0 }], "mid": 7, "statusCode": 0}

方法列表 返回类型 方法和说明 static boolean putCache(String key, String value) 存入缓存信息 static boolean putCache(String key, String value, int time) 存入带超时时间缓存信息 static String getCache(String key) 获取缓存信息 static long removeCache(String key) 移除缓存信息 static String get(String key) 获取字典缓存信息

方法详情 public static boolean putCache(String key, String value) 存入缓存信息 输入参数 key：缓存信息的key值。 value：缓存的信息。 返回信息 返回对应的boolean值 public static boolean putCache(String key, String value, int time) 存入带超时时间缓存信息 输入参数 key：缓存信息的key值。 value：缓存的信息。 time：超时时间，单位秒。超时后缓存的信息将被删除，获取该缓存信息将返回空值。 返回信息 返回对应的boolean值 public static String getCache(String key) 获取缓存信息 输入参数 key：缓存信息的key值 返回信息 返回key值对应的缓存信息 public static long removeCache(String key) 移除缓存信息 输入参数 key：待移除缓存信息的key值 返回信息 返回执行结果 public static String get(String key) 获取字典缓存信息 输入参数 key：字典缓存信息的key值 返回信息 返回key值对应的字典缓存信息

使用示例 在使用CacheUtils之前，需要new一个新对象方可调用。 CacheUtils的get方法只允许使用白名单里的几项作为键： "DICT:api_gw_rest_addr"、"DICT:api_gw_rest_float_addr"、"DICT:api_gw_rest_eip_addr"、"DICT:livedata_private_address" 示例： importClass(com.huawei.livedata.lambdaservice.util.CacheUtils);function execute(data) { var cacheUtils = new CacheUtils var value = cacheUtils.get("DICT:livedata_private_address") return value} 返回的结果为livedata的内网地址。 putCache方法和getCache方法可以实现缓存的使用示例： importClass(com.huawei.livedata.lambdaservice.util.CacheUtils);function execute(data) { var cacheUtils = new CacheUtils code = cacheUtils.putCache("age", "20") if (code != true) { return code } var name = cacheUtils.getCache("age") return name} 返回的结果为20。

使用示例 importClass(com.roma.apic.livedata.client.v1.SoapClient);importClass(com.roma.apic.livedata.config.v1.SoapConfig);importClass(com.roma.apic.livedata.common.v1.XmlUtils);function execute(data) { var soap = new SoapConfig(); soap.setUrl("http://test.webservice.com/ws"); soap.setNamespace("http://spring.io/guides/gs-producing-web-service"); soap.setOperation("getCountryRequest"); soap.setNamespacePrefix("ser"); soap.setBodyPrefix("ser"); soap.setEnvelopePrefix("soapenv"); var content = { "getCountryRequest": { "ser:name": "Spain" }, }; soap.setContent(content); var client = new SoapClient(soap); var result = client.execute(); var body = result.getBody(); return XmlUtils.toJson(body);}

方法列表 返回类型 方法和说明 String get(String key) 返回redis缓存中key对应的value值 String put(String key, int expireTime, String value) 更新redis缓存内容、过期时间，返回执行结果 String put(String key, String value) 更新redis缓存内容，返回执行结果 Long remove(String key) 删除指定key值的缓存消息