华为云用户手册

准备开发环境 安装开发工具 请根据所使用语言选择适合的开发工具。 安装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或以上版本。

调用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()

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。

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

方法列表 返回类型 方法和说明 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" }] }]}

方法详情 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表示交换器配置。

数据源说明 假设数据库里面有一张表，表结构如下建表语句所示： 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;

准备开发环境 安装开发工具 请根据所使用语言选择适合的开发工具。 安装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官方下载页面下载。

数据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 ]}

开发规范 开发工具版本要求： 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}

使用示例 在使用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);}

方法列表 返回类型 方法和说明 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值对应的字典缓存信息

使用示例 importClass(com.roma.apic.livedata.client.v1.RedisClient);function execute(data) { var redisClient = new RedisClient; var count = redisClient.get("visit_count") if (!count) { redisClient.put("visit_count", 1); }else { redisClient.put("visit_count", parseInt(count) + 1); } return redisClient.get("visit_count");}

方法详情 public String get(String key) 返回redis缓存中key对应的value值 输入参数 key：key值 返回信息 redis缓存中key对应的value值 public String put(String key, int expireTime, String value) 更新redis缓存内容、过期时间 输入参数 key：待更新缓存的key值 expireTime：待更新缓存内容的过期时间，单位为秒 value：待更新缓存的value值 返回信息 返回执行结果 public String put(String key, String value) 更新redis缓存内容 输入参数 key：待更新缓存的key值 value：待更新缓存的value值 返回信息 返回执行结果 public Long remove(String key) 删除指定key值的缓存消息 输入参数 key：待删除缓存的key值 返回信息 返回执行结果

方法列表 返回类型 方法和说明 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值的缓存消息

前提条件 已获取API的调用信息，具体请参见开发准备。 已安装开发工具和Python开发语言环境，具体请参见开发准备。 Python安装完成后，在命令行中使用pip安装“requests”库。 pip install requests 如果pip安装requests遇到证书错误，请下载并使用Python执行此文件，升级pip，然后再执行以上命令安装。 已在IntelliJ IDEA中安装Python插件，如果未安装，请按照图1所示安装。 图1 安装Python插件

调用API示例 在工程中引入apig_sdk。 from apig_sdk import signerimport requestsimport os 生成一个新的Signer，输入API所授权凭据的Key和Secret，可参考获取API的调用信息获取。 sig = 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 = os.getenv('HUAWEICLOUD_SDK_AK')sig.Secret = os.getenv('HUAWEICLOUD_SDK_SK') 生成一个Request对象，指定方法名、请求url、header和body，可参考获取API的调用信息获取。 r = signer.HttpRequest("POST", "https://c967a237-cd6c-470e-906f-a8655461897e.apigw.exampleRegion.com/app1?a=1", {"x-stage": "RELEASE"}, "body") 进行签名，执行此函数会在请求参数中添加用于签名的X-Sdk-Date头和Authorization头。 X-Sdk-Date是一个必须参与签名的请求消息头参数。 sig.Sign(r) 访问API，查看访问结果。 //若使用系统分配的子 域名 访问https请求的API时，需要在data=r.body后添加“,verify=False”，用来忽略证书校验resp = requests.request(r.method, r.scheme + "://" + r.host + r.uri, headers=r.headers, data=r.body)print(resp.status_code, resp.reason)print(resp.content)

步骤3：计算签名 将APP secret和创建的待签字符串作为加密哈希函数的输入，计算签名，将二进制值转换为十六进制表示形式。 伪代码如下： signature = HexEncode(HMAC(APP secret, string to sign)) 其中HMAC指密钥相关的哈希运算，HexEncode指转十六进制。伪代码中参数说明如表1所示。 表1 参数说明 参数名称 参数解释 APP secret 签名密钥 string to sign 创建的待签字符串 假设APP secret为12345678-1234-1234-1234-123456781234，则计算得到的signature为： 121c2501e8951ff7d5574423939b9acaa283e55a27c0107d767bb0d68b5ffcab

步骤1：构造规范请求 使用APP方式进行签名与认证，首先需要规范请求内容，然后再进行签名。客户端与APIC使用相同的请求规范，可以确保同一个HTTP请求的前后端得到相同的签名结果，从而完成身份校验。 HTTP请求规范伪代码如下： CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload)) 通过以下示例来说明规范请求的构造步骤。 假设原始请求如下： GET https://30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.com/app1?b=2&a=1 HTTP/1.1Host: 30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.comX-Sdk-Date: 20180330T123600Z 构造HTTP请求方法（HTTPRequestMethod），以换行符结束。 HTTP请求方法，如GET、PUT、POST等。请求方法示例： GET 添加规范URI参数（CanonicalURI），以换行符结束。 释义： 规范URI，即请求资源路径，是URI的绝对路径部分的URI编码。 格式： 根据RFC 3986标准化URI路径，移除冗余和相对路径部分，路径中每个部分必须为URI编码。如果URI路径不以“/”结尾，则在尾部添加“/”。 举例： 示例中的URI：/app1，此时规范的URI编码为： GET/app1/ 计算签名时，URI必须以“/”结尾。发送请求时，可以不以“/”结尾。 添加规范查询字符串（CanonicalQueryString），以换行符结束。 释义： 查询字符串，即查询参数。如果没有查询参数，则为空字符串，即规范后的请求为空行。 格式： 规范查询字符串需要满足以下要求： 根据以下规则对每个参数名和值进行URI编码： 请勿对RFC 3986定义的任何非预留字符进行URI编码，这些字符包括：A-Z、a-z、0-9、-、_、.和~。 使用%XY对所有非预留字符进行百分比编码，其中X和Y为十六进制字符（0-9和A-F）。例如，空格字符必须编码为%20，扩展UTF-8字符必须采用“%XY%ZA%BC”格式。 对于每个参数，追加“URI编码的参数名称=URI编码的参数值”。如果没有参数值，则以空字符串代替，但不能省略“=”。 例如以下含有两个参数，其中第二个参数parm2的值为空。 parm1=value1&parm2= 按照字符代码以升序顺序对参数名进行排序。例如，以大写字母F开头的参数名排在以小写字母b开头的参数名之前。 以排序后的第一个参数名开始，构造规范查询字符串。 举例： 示例中包含两个可选参数：a、b GET/app1/a=1&b=2 添加规范消息头（CanonicalHeaders），以换行符结束。 释义： 规范消息头，即请求消息头列表。包括签名请求中的所有HTTP消息头列表。消息头必须包含X-Sdk-Date，用于校验签名时间，格式为ISO8601标准的UTC时间格式：YYYYMMDDTHHMMSSZ。如果API发布到非RELEASE环境时，需要增加自定义的环境名称。 客户端须注意本地时间与时钟服务器的同步，避免请求消息头X-Sdk-Date的值出现较大误差。 ROMA Connect除了校验X-Sdk-Date的时间格式外，还会校验该时间值与收到请求的时间差，如果时间差超过15分钟，ROMA Connect将拒绝请求。 格式： CanonicalHeaders由多个请求消息头共同组成，CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ...，其中每个请求消息头（CanonicalHeadersEntry）的格式为Lowercase(HeaderName) + ':' + Trimall(HeaderValue) + '\n' Lowercase表示将所有字符转换为小写字母的函数。 Trimall表示删除值前后的多余空格的函数。 最后一个请求消息头也会携带一个换行符。叠加规范中CanonicalHeaders自身携带的换行符，因此会出现一个空行。 举例： GET/app1/a=1&b=2host:30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.comx-sdk-date:20180330T123600Z 规范消息头需要满足以下要求： 将消息头名称转换为小写形式，并删除前导空格和尾随空格。 按照字符代码对消息头名称进行升序排序。 例如原始消息头为： Host:30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.com\nContent-Type: application/json;charset=utf8\nMy-header1: a b c \nX-Sdk-Date:20180330T123600Z\nMy-Header2: "a b c" \n 规范消息头为： content-type:application/json;charset=utf8\nhost:30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.com\nmy-header1:a b c\nmy-header2:"a b c"\nx-sdk-date:20180330T123600Z\n 添加用于签名的消息头声明（SignedHeaders），以换行符结束。 释义： 用于签名的请求消息头列表。通过添加此消息头，向APIC告知请求中哪些消息头是签名过程的一部分，以及在验证请求时APIC可以忽略哪些消息头。X-Sdk-date必须作为已签名的消息头。 格式： SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... 已签名的消息头需要满足以下要求：将已签名的消息头名称转换为小写形式，按照字符代码对消息头进行排序，并使用“;”来分隔多个消息头。 Lowercase表示将所有字符转换为小写字母。 举例： 以下表示有两个消息头参与签名：host、x-sdk-date GET/app1/a=1&b=2host:30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.comx-sdk-date:20180330T123600Zhost;x-sdk-date 使用SHA 256哈希函数以基于HTTP或HTTPS请求正文中的body体（RequestPayload），创建哈希值。 释义： 请求消息体。消息体需要做两层转换：HexEncode(Hash(RequestPayload))，其中Hash表示生成消息摘要的函数，当前支持SHA-256算法。HexEncode表示以小写字母形式返回摘要的Base-16编码的函数。例如，HexEncode("m") 返回值为“6d”而不是“6D”。输入的每一个字节都表示为两个十六进制字符。 计算RequestPayload的哈希值时，对于“RequestPayload==null”的场景，直接使用空字符串""来计算。 举例： 本示例为GET方法，body体为空。经过哈希处理的body（空字符串）如下： GET/app1/a=1&b=2host:30030113-3657-4fb6-a7ef-90764239b038.apigw.exampleRegion.comx-sdk-date:20180330T123600Zhost;x-sdk-datee3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 对构造好的规范请求进行哈希处理，算法与对RequestPayload哈希处理的算法相同。经过哈希处理的规范请求必须以小写十六进制字符串形式表示。 算法伪代码：Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))) 经过哈希处理的规范请求示例： aa521bbe74d13cd8cf536c1a03a5dd85d1934179d33d47110b528eae8b7251e1

APP认证流程 构造规范请求。 将待发送的请求内容按照与APIC后台约定的规则组装，确保客户端签名、APIC后台认证时使用的请求内容一致。 使用规范请求和其他信息创建待签字符串。 使用AK/SK和待签字符串计算签名。 将生成的签名信息作为请求消息头添加到HTTP请求中，或者作为查询字符串参数添加到HTTP请求中。 APIC收到请求后，执行1~3，计算签名。 将3中的生成的签名与5中生成的签名进行比较，如果签名匹配，则处理请求，否则将拒绝请求。 APP签名仅支持Body体12M及以下的请求签名。

步骤2：创建待签字符串 对HTTP请求进行规范并取得请求的哈希值后，将其与签名算法、签名时间一起组成待签名字符串。 StringToSign = Algorithm + \n + RequestDateTime + \n + HashedCanonicalRequest 伪代码中参数说明如下。 Algorithm 签名算法。对于SHA 256，算法为SDK-HMAC-SHA256。 RequestDateTime 请求时间戳。与请求消息头X-Sdk-Date的值相同，格式为YYYYMMDDTHHMMSSZ。 HashedCanonicalRequest 经过哈希处理的规范请求。 上述例子得到的待签字符串为： SDK-HMAC-SHA25620180330T123600Zaa521bbe74d13cd8cf536c1a03a5dd85d1934179d33d47110b528eae8b7251e1