华为云用户手册

方案概述 基于设备管理服务去实现一个物联网解决方案时，需要完成以下开发操作： 开发操作 开发说明 平台侧的开发 主要包括Profile的开发和编解码插件的开发。编解码插件的开发仅针对上报数据为二进制码流格式的设备，对于上报数据为JSON格式的设备不需要开发编解码插件。 设备侧的开发 主要为设备与物联网平台的集成对接开发，包括设备接入物联网平台、业务数据上报和对平台下发控制命令的处理。 应用侧的开发 主要为业务应用与物联网平台的集成对接开发，包括API接口的调用、业务数据的获取和HTTPS证书的管理。 基于物联网平台开发一个物联网解决方案的工作流程请参考从这里开始。

使用在线模拟器调试 模拟器在线调测具备设备模拟和应用模拟功能，可以对定义的Profile文件和编解码插件进行调试，用户可以直观的感受设备上报数据到物联网平台，以及使用物联网平台下发远程控制命令。 在“产品开发”页面进入到创建的产品中，选择“在线调测”，并单击“新增测试设备”。 选择“没有真实的物理设备”，使用模拟器进行调测，单击“创建”后，系统会默认创建一个模拟设备，并接入调测界面。 模拟设备数据上报场景，假设上报路灯采集的光照强度为：20，路灯开关状态为：0（关闭），则在设备模拟器中，输入十六进制码流：1400（光照强度消息为第一个字节，对应的十六进制码流为14；路灯开关状态为第二字节，对应的十六进制码流为00），然后单击“发送”，我们可以在应用模拟器中看到转换为JSON格式的数据为："Light_Intensity": 20, "Light_Status": 0。 模拟远程下发控制命令场景，在应用模拟器中，选择服务：StreetLight，命令：SWITCH_LIGHT，命令取值为：ON，单击“立即发送”，我们可以在设备模拟器中看到转换为十六进制的码流：4F4E（经ASCLL码转为为十六进制）。

产品在线开发 产品模型（也称Profile）用于描述设备具备的能力和特性。开发者通过定义Profile文件，在物联网平台构建一款设备的抽象模型，使平台理解该款设备支持的服务、属性、命令等信息，例如温度、光强度、开关等。 本示例以一款智慧路灯为例进行描述，假设路灯设备上报一条数据消息，包含路灯的光照强度（Light_Intensity）和路灯的开关状态（Light_Status）；支持远程控制路灯开关状态的命令（SWITCH_LIGHT）。 在“产品开发”界面，点击“新建产品”，然后选择“自定义产品”。 在弹出的对话框中，设置产品信息，完成后点击“创建”。 进入到Profile定义界面后，点击“新建服务”，填写服务信息，然后点击“√”。 定义路灯上报的环境光强度和路灯开关状态的属性。首先输入“服务名称”：StreetLight，然后点击“新增属性”。 首先定义一条属性为：路灯采集的当前环境的光照强度，数据类型为int，光照强度范围为：0～100。 再点击“添加属性”按钮，定义一条属性为：路灯当前的开关灯状态，数据类型为int，0代表关闭，1代表打开状态。 接下来定义远程控制开关灯状态的命令。点击“添加命令”按钮，定义命令名称为：SWITCH_LIGHT。 点击“添加下发命令字段”，命令名称为：SWITCH_LIGHT，数据类型为：string，长度为：3个字符，枚举值为：ON,OFF。 点击“确定”按钮，完成该路灯的Profile文件创建。

编解码插件在线开发 通常情况下设备为了省电，设备会采用“二进制”格式上报数据，编解码插件的作用就是将设备上报的“二进制”格式数据，按照Profile文件的定义的属性转换为“JSON”格式数据，便于物联网平台和应用服务器识别。同时，用户远程下发控制命令时，物联网平台会将“JSON”格式的命令转换为“二进制”格式数据下发给设备。 注：如果设备本身上报的是JSON格式数据，则不需要定义编解码插件，如使用Agent Lite接入的设备。 在“产品开发”页面进入到创建的产品中，选择“编解码插件开发”。 在“在线编解码插件编辑器”中，点击“新增消息”。 输入消息名：LightData，消息类型选择：数据上报，然后再点击“添加字段”。 输入上报消息的名字：LightIntensity，数据类型：int8u（8位无符号整型），长度：1字节，单击“完成”。 再次单击“添加字段”，添加路灯上报的路灯开关状态数据。 输入名字：LightStatus，数据类型：int8u（8位无符号整型），长度：1字节，单击“完成”。 单击“完成”，完成路灯上报数据的编解码定义。 再次单击“新增消息”，定义远程控制路灯开关的命令对应的编解码插件消息。 输入消息名：SwitchStatus，消息类型选择：命令下发，然后再点击“添加字段”。 输入名字：SwitchStatus，数据类型：string（字符串类型），长度：3字符，单击“完成”。 单击“完成”，完成远程控制命令的编解码定义。 拖动右侧“设备模型”区域的属性字段和命令字段（Profile文件定义的字段），与编解码插件定义的数据上报消息和命令下发消息的相应字段建立映射关系。 编解码插件与Profile文件建立映射完成后，单击右上角“保存”，并单击“部署”，完成编解码插件的部署。

开发中心申请和创建项目 用户第一次使用物联网平台云服务时，首先需要申请开通“开发中心”服务。基于开发中心，用户可以在线开发设备的Profile文件和编解码插件；另外开发中心提供了设备和应用模拟器，可以便捷地调测开发的Profile文件和编解码插件的正确性。 登录华为云官方网站，访问IoT设备管理服务。 在设备管理云服务首页，点击“开发中心”开通业务。 填写开通信息，本示例以选择“智能路灯解决方案”为例，点击“立即开通”。 （可选）进入“开发中心”首页后，如果用户是第一次使用，首先需要点击右上角的“厂商信息”，编辑并完善厂商信息后，返回主页。 在“开发中心”首页，点击“新建项目”，创建一个新的物联网产品项目，填写项目名称、所属行业后，点击“确定”。 创建完项目后，会生成应用ID和应用密钥，请将密钥下载到本地并妥善保管，然后进入项目。 应用密钥用于应用服务器接入的鉴权，在界面上不可见，请妥善保管，如果忘记了密钥，可以在“对接信息”功能中，对密钥进行重置。 项目创建完成后，可以在“对接信息”中，查看项目的基本信息，例如设备接入信息、应用接入信息、重置密钥等。

业务接口调用方法 设置好Constant.py后才能调用其他业务接口。所有业务接口的测试都在“invokeapiTest”中。以如下几个接口为例说明如何调用业务接口： 关于哪些参数需要设置，请查看《应用侧Python SDK API参考》对于可选参数，如果业务不需要，可以不设置。 配置日志 1 2 3 4 5 6 7 8 91011 # 在每个业务接口中都配置了日志，具体日志实现可参考LogUtil.py:# 开发者可通过修改入参来控制日志的输出，以下三个参数都可自行设置；# logPath：日志的输出路径，默认在工作路径d:/python_sdk/log/ # level：日志等级，默认DEBUG（最低等级，即大于等于该等级的日志级别都会输出），如果level=0没有日志输出# logFilename：日志名称def setLogConfig(self, logPath=os.path.join(Constant.workPath, 'log/'), level=logging.DEBUG, logFilename="python_sdk.log"): 鉴权 1 2 3 4 5 6 7 8 910111213141516 # 在AuthenticationTest.py中对鉴权和刷新token接口进行测试:if __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化Authentication() authentication = Authentication() # 调用鉴权类实例authentication提供的业务接口，如getAuthToken ag = authentication.getAuthToken(Constant().clientInfo()) print("====== get access token ======") print("result:", ag + "\n")# 从返回的ag中获取需要的参数，如accessToken authOutDTO = AuthOutDTO()authOutDTO.setAccessToken(json.loads(ag)['accessToken'])print("token", authOutDTO.getAccessToken()) 订阅 1 2 3 4 5 6 7 8 910111213141516171819202122232425 # 在SubscriptionManagementTest.py中对订阅订阅平台业务数据接口进行测试:class SubscriptionManagementTest(object): def subDeviceBusinessData(self): sdbdInDTO = SubDeviceBusinessDataInDTO() sdbdInDTO.notifyType = "bindDevice" sdbdInDTO.callbackUrl = "https://XXX.XXX.XXX.XXX:443/callbackurltest" return sdbdInDTOif __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化 smTest = SubscriptionManagementTest()subscriptionManagement = SubscriptionManagement() # get accessToken at first result = Authentication().getAuthToken(Constant().clientInfo()) authOutDTO = AuthOutDTO() authOutDTO.setAccessToken(json.loads(result)['accessToken']) accessToken = authOutDTO.getAccessToken() # 调用订阅类实例subscriptionManagement提供的业务接口，如subDeviceData ss = subscriptionManagement.subDeviceBusinessData(smTest.subDeviceBusinessData(), accessToken) print("====== subscribe to device business data notification ======") print("result:", ss + "\n") 注册设备 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930 # 在DeviceManagementTest.py中对注册设备接口进行测试:class DeviceManagementTest(object): def regDirectDeviceInfo(self): rddInDto = RegDirectDeviceInDTO() rddInDto.nodeId = "AAA" + str(random.randint(0, 9999)) return rddInDtoif __name__ == "__main__": from com.huawei.iotplatform.utils.LogUtil import Log # 实例化 dmTest = DeviceManagementTest() deviceManagement = DeviceManagement() # get accessToken at first result = Authentication().getAuthToken(Constant().clientInfo()) authOutDTO = AuthOutDTO() authOutDTO.setAccessToken(json.loads(result)['accessToken']) accessToken = authOutDTO.getAccessToken() # 调用设备管理类实例deviceManagement提供的业务接口，如regDirectDevice dr = deviceManagement.regDirectDevice(dmTest.regDirectDeviceInfo(), None, accessToken) print("====== register a new device ======") print("result:", dr + "\n")# 从返回的dr中获取需要的参数，如deviceIdrddod = RegDirectDeviceOutDTO()rddod.setDeviceId(json.loads(dr)['deviceId'])deviceId = rddod.getDeviceId()print("deviceId==", deviceId + "\n")

配置平台信息及证书 配置文件（application.ini）以及证书都分别放置在工作路径“d:/python_sdk/”下面的cert 和resources文件夹中，用户也可自行设置工作路径。 平台IP、端口、appId和密码都是从配置文件中读取的，因此，当这些信息发生变化时，只要修改配置文件，不用修改应用服务器的代码。 [CLIENT_INFO]platformIp = 100.100.100.100platformPort = 8743appId = FT8EjQ8O****VbW60Qb8xvgasecret = TtuK4Paf*****yAv66himUk8a 在“Constant.py”中，读取证书和CLIENT_INFO。 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627282930 class Constant(object):# 工作路径 workPath = os.path.join('d:/python_sdk/')# 读取证书def readCertificate(self): certFilePath = os.path.join(Constant.workPath, 'cert/client.crt') certFilePath2 = os.path.join(Constant.workPath, 'cert/client.key') cert = (certFilePath, certFilePath2)return cert# 读取配置文件def readConfFile(self): configFilePath = os.path.join(Constant.workPath, 'resources/application.ini') cf.read(configFilePath) platformIp = cf.get("CLIENT_INFO", "platformIp") platformPort = cf.get("CLIENT_INFO", "platformPort") appId = cf.get("CLIENT_INFO", "appId") secret = cf.get("CLIENT_INFO", "secret")return platformIp, platformPort, appId, secret# 设置平台对接信息def clientInfo(self): clientInfo = ClientInfo() clientInfo.setPlatformIp((Constant().readConfFile())[0]) clientInfo.setPlatformPort((Constant().readConfFile())[1]) clientInfo.setAppId((Constant().readConfFile())[2]) clientInfo.setSecret((Constant().readConfFile())[3]) clientInfo = DictUtil.dto2dict(clientInfo)return clientInfo

编解码插件质检 编解码插件的质检用于检验编解码是否可以正常使用。 获取编解码插件检测工具。 将检测工具“pluginDetector.jar”、Profile文件的“devicetype-capability.json”和需要检测的编解码插件包“package.zip”和tool文件夹放在同一个目录下。 获取设备数据上报的码流，并在检测工具的“data report”页签，将码流以十六进制格式输入，例如：AA72000032088D0320623399。 点击检测工具的“start detect”，查看解码后的json数据。 日志文本框会打印解码数据，如果提示“report data is success”，表示解码成功。 如果提示“ERROR”，表示解码出现错误。 当解码成功后，检测工具会继续调用编解码插件包的encode方法，对应答消息进行编码。 当提示“encode ack result success”时，表示对设备的应答消息编码成功。 获取应用服务器下发的命令（应用服务器通过调用物联网平台的“创建设备命令”接口进行命令下发），并在检测工具的“data report”页签输入。 点击检测工具的“start detect”，检测工具会调用encode接口对控制命令进行编码。 如果提示“encode cmd result success”，表示对命令编码成功；如果提示“ERROR”，表示对命令编码出现错误。 命令示例： { "identifier": "123", "msgType": "cloudReq", "serviceId": "NBWaterMeterCommon", "cmd": "SET_DEVICE_LEVEL", "mid": 2016, "paras": { "value": "10" }, "hasMore": 0 } 获取设备命令执行结果上报的码流，并在检测工具的“data report”页签，将码流以十六进制格式输入，例如：AA7201000107E0。 点击检测工具的“start detect”，查看解码后的Json数据。 日志文本框会打印解码数据，如果提示“report command result success”，表示解码成功；如果提示“ERROR”，表示解码出现错误。

编解码插件打包 插件变成完成后，需要使用Maven打包成jar包，并制作成插件包。 Maven打包 打开DOS窗口，进入“pom.xml”所在的目录。 输入maven打包命令：mvn package。 DOS窗口中显示“BUILD SUCCESS”后，打开与“pom.xml”目录同级的target文件夹，获取打包好的jar包。 jar包命名规范为：设备类型-厂商ID-设备型号-版本.jar，例如：WaterMeter-Huawei-NBIoTDevice-version.jar。 com目录存放的是class文件。 META-INF下存放的是OSGI框架下的jar的描述文件（根据pom.xml配置生成的）。 OSGI-INF下存放的是服务配置文件，把编解码注册为服务，供平台调用（只能有一个xml文件）。 其他jar是编解码引用到的jar包。 制作插件包 新建文件夹命名为“package”，包含一个“preload/”子文件夹。 将打包好的jar包放到“preload/”文件夹。 在“package”文件夹中，新建“package-info.json”文件。该文件的字段说明和模板如下： 注：“package-info.json”需要以UTF-8无BOM格式编码。仅支持英文字符。 表4 “package-info.json”字段说明 字段名 字段描述 是否必填 specVersion 描述文件版本号，填写固定值："1.0"。 是 fileName 软件包文件名，填写固定值："codec-demo" 是 version 软件包版本号。描述package.zip的版本，请与下面的bundleVersion取值保持一致。 是 deviceType 设备类型，与Profile文件中的定义保持一致。 是 manufacturerName 制造商名称，与Profile文件中的定义保持一致，否则无法上传到平台。 是 model 产品型号，与Profile文件中的定义保持一致。 是 platform 平台类型，本插件包运行的物联网平台的操作系统，填写固定值："linux"。 是 packageType 软件包类型，该字段用来描述本插件最终部署的平台模块，填写固定值："CIGPlugin"。 是 date 出包时间，格式为："yyyy-MM-dd HH-mm-ss"，如"2017-05-06 20:48:59"。 否 description 对软件包的自定义描述。 否 ignoreList 忽略列表，默认为空值。 是 bundles 一组bundle的描述信息。 注：bundle就是压缩包中的jar包，只需要写一个bundle。 是 表5 bundles的字段说明 字段名 字段描述 是否必填 bundleName 插件名称，和上文中pom.xml的Bundle-SymbolicName保持一致。 是 bundleVersion 插件版本，与上面的version取值保持一致。 是 priority 插件优先级，可赋值默认值：5。 是 fileName 插件jar的文件名称。 是 bundleDesc 插件描述，用来介绍bundle功能。 是 versionDesc 插件版本描述，用来介绍版本更迭时的功能特性。 是 package-info.json文件模板： { "specVersion":"1.0", "fileName":"codec-demo", "version":"1.0.0", "deviceType":"WaterMeter", "manufacturerName":"Huawei", "model":"NBIoTDevice", "description":"codec", "platform":"linux", "packageType":"CIGPlugin", "date":"2017-02-06 12:16:59", "ignoreList":[], "bundles":[ { "bundleName": "WaterMeter-Huawei-NBIoTDevice", "bundleVersion": "1.0.0", "priority":5, "fileName": "WaterMeter-Huawei-NBIoTDevice-1.0.0.jar", "bundleDesc":"", "versionDesc":"" }] } 选中“package”文件夹中的全部文件，打包成zip格式（“package.zip”）。 注：“package.zip”中不能包含“package”这层目录。

编解码插件的输入/输出格式样例 假定某款水表支持的服务定义如下： 服务类型 属性名称 属性说明 属性类型（数据类型） Battery - - - - batteryLevel 电量(0--100)% int Meter - - - - signalStrength 信号强度 int - currentReading 当前读数 int - dailyActivityTime 日激活通讯时长 string 那么数据上报时decode接口的输出： { "identifier": "12345678", "msgType": "deviceReq", "data": [ { "serviceId": "Meter", "serviceData": { "currentReading": "46.3", "signalStrength": 16, "dailyActivityTime": 5706 }, "eventTime": "20160503T121540Z" }, { "serviceId": "Battery", "serviceData": { "batteryLevel": 10 }, "eventTime": "20160503T121540Z" } ]} 收到数据上报后，平台对设备的应答响应，调用encode接口编码，输入为 { "identifier": "123", "msgType": "cloudRsp", "request"：[ 1, 2 ], "errcode": 0, "hasMore": 0} 假定某款水表支持的命令定义如下： 基本功能名称 分类 名称 命令参数 数据类型 枚举值 WaterMeter 水表 - - - - - CMD SET_TEMPERATURE_READ_PERIOD - - - - - - value int - - RSP SET_TEMPERATURE_READ_PERIOD_RSP - - - - - - result int 0表示成功，1表示输入非法，2表示执行失败 那么命令下发调用encode接口时，输入为 { "identifier": "12345678", "msgType": "cloudReq", "serviceId": "WaterMeter", "cmd": "SET_TEMPERATURE_READ_PERIOD", "paras": { "value": 4 }, "hasMore": 0} 收到设备的命令应答后，调用decode接口解码，解码的输出 { "identifier": "123", "msgType": "deviceRsp", "errcode": 0, "body": { "result": 0 }}

decode接口说明 decode接口的入参binaryData为设备发过来的CoAP报文的payload部分。 设备的上行报文有两种情况需要插件处理（消息④是模组回复的协议ACK，无需插件处理）： 设备上报数据（对应图中的消息①） 字段名 类型 是否必填 参数描述 identifier String 否 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。 msgType String 是 固定值"deviceReq"，表示设备上报数据。 hasMore Int 否 表示设备是否还有后续数据上报，0表示没有，1表示有。 后续数据是指，设备上报的某条数据可能分成多次上报，在本次上报数据后，物联网平台以hasMore字段判定后续是否还有消息。hasMore字段仅在PSM模式下生效，当上报数据的hasMore字段为1时，物联网平台暂时不下发缓存命令，直到收到hasMore字段为0的上报数据，才下发缓存命令。如上报数据不携带hasMore字段，则物联网平台按照hasMore字段为0处理。 data ArrayNode 是 设备上报数据的内容。 表1 ArrayNode定义 字段名 类型 是否必填 参数描述 serviceId String 是 服务的id。 serviceData ObjectNode 是 一个服务的数据，具体字段在profile里定义。 eventTime String 否 设备采集数据时间（格式：yyyyMMddTHHmmssZ）。 如：20161219T114920Z。 示例： { "identifier": "123", "msgType": "deviceReq", "hasMore": 0, "data": [{"serviceId": "NBWaterMeterCommon","serviceData": { "meterId": "xxxx", "dailyActivityTime": 120, "flow": "565656", "cellId": "5656", "signalStrength": "99", "batteryVoltage": "3.5"},"eventTime": "20160503T121540Z" }, {"serviceId": "waterMeter","serviceData": {"internalTemperature": 256},"eventTime": "20160503T121540Z" }]} 设备对平台命令的应答（对应图中的消息⑤） 字段名 类型 参数描述 是否必填 identifier String 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。 否 msgType String 固定值"deviceRsp"，表示设备的应答消息。 是 mid Int 2字节无符号的命令id。在设备需要返回命令执行结果（deviceRsp）时，用于将命令执行结果（deviceRsp）与对应的命令进行关联。 物联网平台在通过encode接口下发命令时，把物联网平台分配的mid放入码流，和命令一起下发给设备；设备在上报命令执行结果（deviceRsp）时，再将此mid返回给物联网平台。否则物联网平台无法将下发命令和命令执行结果（deviceRsp）进行关联，也就无法根据命令执行结果（deviceRsp）更新命令下发的状态（成功或失败）。 是 errcode Int 请求处理的结果码，物联网平台根据该参数判断命令下发的状态。 0表示成功，1表示失败。 是 body ObjectNode 命令的应答，具体字段由profile定义。 注：body体不是数组。 否 示例： { "identifier": "123", "msgType": "deviceRsp", "mid": 2016, "errcode": 0, "body": { "result": 0 } }

encode接口说明 encode接口的入参是JSON格式的数据，是平台下发的命令或应答。 平台的下行报文可以分为两种情况： 平台对设备上报数据的应答（对应图中的消息②） 表2 平台收到设备的上报数据后对设备的应答encode接口的入参结构定义 字段名 类型 参数描述 是否必填 identifier String 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。 否 msgType String 固定值"cloudRsp"，表示平台收到设备的数据后对设备的应答。 是 request byte[] 设备上报的数据。 是 errcode int 请求处理的结果码，物联网平台根据该参数判断命令下发的状态。 0表示成功，1表示失败。 是 hasMore int 表示平台是否还有后续消息下发，0表示没有，1表示有。 后续消息是指，平台还有待下发的消息，以hasMore字段告知设备不要休眠。hasMore字段仅在PSM模式下生效，且需要“下行消息指示”开启。 是 注：在cloudRsp场景下编解码插件检测工具显示返回null时，表示插件未定义上报数据的应答，设备侧不需要物联网平台给予响应。 示例： { "identifier": "123", "msgType": "cloudRsp", "request": [ 1, 2 ], "errcode": 0, "hasMore": 0 } 平台命令下发（对应图中的消息③） 表3 平台下发命令encode接口的入参结构定义 字段名 类型 参数描述 是否必填 identifier String 设备在应用协议里的标识，物联网平台通过decode接口解析码流时获取该参数，通过encode接口编码时将该参数放入码流。 否 msgType String 固定值"cloudReq"，表示平台下发的请求。 是 serviceId String 服务的id。 是 cmd String 服务的命令名，参见profile的服务命令定义。 是 paras ObjectNode 命令的参数，具体字段由profile定义。 是 hasMore Int 表示平台是否还有后续命令下发，0表示没有，1表示有。 后续命令是指，平台还有待下发的消息，以hasMore字段告知设备不要休眠。hasMore字段仅在PSM模式下生效，且需要“下行消息指示”开启。 是 mid Int 2字节无符号的命令id，由物联网平台内部分配（范围1-65535）。 物联网平台在通过encode接口下发命令时，把物联网平台分配的mid放入码流，和命令一起下发给设备；设备在上报命令执行结果（deviceRsp）时，再将此mid返回物联网平台。否则物联网平台无法将下发命令和命令执行结果（deviceRsp）进行关联，也就无法根据命令执行结果（deviceRsp）更新命令下发的状态（成功或失败）。 是 示例： { "identifier": "123", "msgType": "cloudReq", "serviceId": "NBWaterMeterCommon", "mid": 2016, "cmd": "SET_TEMPERATURE_READ_PERIOD", "paras": { "value": 4 }, "hasMore": 0} }

设备管理 平台为每一个注册到平台上的设备生成了一个deviceId，这是设备在平台上的唯一ID，在接口调用时，每个与设备的相关操作都需要deviceId。开发中心的“设备管理”功能模块呈现本项目中的所有产品下的真实设备和虚拟设备，并提供分类统计、在线调测、设备日志等功能，以便于进行设备管理和问题定位。 在“设备管理”新增真实设备，设备名称由开发者定义。当设备侧开发已经完成时，您可以在开发中心创建真实设备，对真实物理设备、编解码插件、应用服务器等进行端到端调试。 在“设备管理”新增虚拟设备，设备名称由系统生成，名称组成为：“产品名称”+“Simulator”，每款产品下只能够创建一个虚拟设备。当设备侧开发还未完成时，您可以在开发中心创建虚拟设备，对编解码插件、应用服务器等进行调测。

使用虚拟设备调测 在产品开发空间，点击“在线调测”。 在“设备列表”区域，点击“新增测试设备”。 系统将弹出“新增测试设备”窗口，勾选“没有真实的物理设备”，点击“创建”。 在设备列表中，选择新创建的虚拟设备，进入调试界面。虚拟设备名称组成为：“产品名称”+“Simulator”，每款产品下只能够创建一个虚拟设备。 在“设备模拟器”区域，输入十六进制码流或者JSON数据（以十六进制码流为例），点击“发送”，在“应用模拟器”区域查看数据上报的结果，在“消息跟踪”区域查看物联网平台处理日志。 在“应用模拟器”区域进行命令下发，在“设备模拟器”区域查看接收到的命令（以十六进制码流为例），在“消息跟踪”区域查看物联网平台处理日志。

使用真实设备调测 请先参照设备侧开发将设备接入开发中心，开发中心的接入地址请参照平台对接信息获取。 确保设备上报的数据信息与Profile中定义的一致，且如果设备上报的是二进制码流，请确保已经开发了编解码插件。 在产品开发空间，点击“在线调测”。 在“设备列表”区域，点击“新增测试设备”。 系统将弹出“新增测试设备”窗口，勾选“有真实的物理设备”，完成各项参数配置后，点击“创建”。 “设备名称”只允许大小写字母、数字和下划线，需要在产品下保持唯一。 “设备标识”需要在产品下保持唯一，如设备的IMEI、mac等。 “验证码加密”根据设备的实际情况进行配置。 设备创建成功后，将返回“设备ID”和“PSK码”。如果设备使用DTLS协议接入物联网平台，请妥善保存PSK码。 在设备列表中，选择新创建的真实设备，进入调试界面。 将真实设备接入到物联网平台，并进行数据上报，在“应用模拟器”区域查看数据上报的结果，在“消息跟踪”区域查看物联网平台处理日志。 在“应用模拟器”区域进行命令下发，在“消息跟踪”区域查看物联网平台处理日志，在真实设备上查看接收到的命令。

SDK独立运行测试 SDK包中提供了可独立运行的jar包，用于测试平台Restful接口。可独立运行测试的jar包在testSDK目录下： 图1 可独立运行的jar包 修改config.properties后再双击运行runMe.bat即可进行测试。 图2 修改config.properties 如果使用商用证书，请直接将证书放在testSDK目录下面（证书名字不可以与ca.jks或者outgoing.CertwithKey.pkcs12相同），并在config.properties中配置证书名及密码；如果使用测试证书，则不需要修改config.properties中的证书信息。 测试结果会在最前面输出：[y]表示测试通过；[x]则表示出错，请仔细查看该行的错误提示或说明。 运行jar包需要依赖JDK，请确认已安装JDK并设置了系统环境变量。 运行runMe.bat的结果如下：

初始化及证书配置 新建一个NorthApiClient实例，设置好ClientInfo（包括平台IP、端口、appId和密码），再初始化证书。 平台IP、端口、appId和密码都是从配置文件./src/main/resources/application.properties中读取的，因此，当这些信息发生变化时，只要修改配置文件，不用修改应用服务器的代码。本章节所指的证书是平台提供的，在调用平台接口过程中使用；一般情况下，与回调使用的证书不一样。 使用测试证书： 1 2 3 4 5 6 7 8 9101112 NorthApiClient northApiClient = new NorthApiClient();PropertyUtil.init("./src/main/resources/application.properties");ClientInfo clientInfo = new ClientInfo();clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));clientInfo.setAppId(PropertyUtil.getProperty("appId"));clientInfo.setSecret(PropertyUtil.getProperty("secret"));northApiClient.setClientInfo(clientInfo);northApiClient.initSSLConfig();//默认使用测试证书，且不进行主机名校验 如果不使用测试证书，可使用指定证书（如商用证书）： 1 2 3 4 5 6 7 8 9101112131415161718 NorthApiClient northApiClient = new NorthApiClient();PropertyUtil.init("./src/main/resources/application.properties");ClientInfo clientInfo = new ClientInfo();clientInfo.setPlatformIp(PropertyUtil.getProperty("platformIp"));clientInfo.setPlatformPort(PropertyUtil.getProperty("platformPort"));clientInfo.setAppId(PropertyUtil.getProperty("appId"));clientInfo.setSecret(getAesPropertyValue("secret"));SSLConfig sslConfig= new SSLConfig();sslConfig.setTrustCAPath(PropertyUtil.getProperty("newCaFile"));slConfig.setTrustCAPwd(getAesPropertyValue("newCaPassword"));slConfig.setSelfCertPath(PropertyUtil.getProperty("newClientCertFile"));slConfig.setSelfCertPwd(getAesPropertyValue("newClientCertPassword"));northApiClient.setClientInfo(clientInfo);northApiClient.initSSLConfig(sslconfig); //使用指定的证书，且默认使用严格主机名校验 使用指定证书时，如果不使用严格主机名校验，在调用northApiClient.initSSLConfig(sslconfig)之前可以自行设置主机名校验方法： 1234567 northApiClient.setHostnameVerifier(new HostnameVerifier() { public boolean verify(String arg0, SSLSession arg1) { // 自定义主机名校验 …… return true; }}); 主机名校验方法应以安全为原则，不应该直接返回true。

开发环境要求 开发平台 开发环境 配套要求 推荐的操作系统 IoT 1) J2EE for Java Developers 2) Maven插件：m2e - Maven Integration for Eclipse (includes Incubating components) JDK 1.8及以上版本 Windows7 SDK包为纯JAVA的JAR包，在使用上没有特殊限制，JDK在1.8及以上版本即可。

业务接口调用方法 设置好NorthApiClient实例后才能调用其他业务接口。以如下几个接口为例说明如何调用业务接口。 关于哪些参数需要设置，请查看《应用侧JAVA SDK API参考》。对于可选参数，如果业务不需要，可以不设置或者设置为null。 鉴权 123456789 //得到NorthApiClient实例后，再使用northApiClient得到鉴权类实例Authentication authentication = new Authentication(northApiClient);//调用鉴权类实例authentication提供的业务接口，如getAuthTokenAuthOutDTO authOutDTO = authentication.getAuthToken();//从返回的结构体authOutDTO中获取需要的参数，如accessToken，不同接口的token是通用的，只用获取一次，token有效期为1小时。在即将到1小时前，可调用刷新鉴权接口重新获取tokenString accessToken = authOutDTO.getAccessToken(); 订阅 1 2 3 4 5 6 7 8 9101112131415 //得到NorthApiClient实例后，再使用northApiClient得到订阅类实例SubscriptionManagement subscriptionManagement = new SubscriptionManagement(northApiClient);//先设置好subDeviceData的第一个入参SubDeviceDataInDTO结构体SubDeviceDataInDTO sddInDTO = new SubDeviceDataInDTO();sddInDTO.setNotifyType("deviceDataChanged");//需要根据实际情况修改回调的ip和端口ddInDTO.setCallbackUrl("https://XXX.XXX.XXX.XXX:8099/v1.0.0/messageReceiver");try { //调用订阅类实例subscriptionManagement提供的业务接口，如subDeviceData SubscriptionDTO subDTO = subscriptionManagement.subDeviceData(sddInDTO, null, accessToken); System.out.println(subDTO.toString());} catch (NorthApiException e) { System.out.println(e.toString());} 注册设备 1 2 3 4 5 6 7 8 910111213141516 //得到NorthApiClient实例后，再使用northApiClient得到设备管理类实例DeviceManagement deviceManagement = new DeviceManagement(northApiClient);//设置好注册设备接口的第一个入参RegDirectDeviceInDTO2结构体RegDirectDeviceInDTO2 rddInDTO = new RegDirectDeviceInDTO2();String nodeid = "86370303XXXXXX"; //this is a test imeiString verifyCode = nodeid;rddInDTO.setNodeId(nodeid);rddInDTO.setVerifyCode(verifyCode);rddInDTO.setTimeout(timeout);//调用设备管理类实例deviceManagement提供的业务接口，如regDirectDeviceRegDirectDeviceOutDTO rddod = deviceManagement.regDirectDevice(rddInDTO, null, accessToken);//从返回的结构体rddod中获取需要的参数，如deviceIdString deviceId = rddod.getDeviceId();

高质量素材规范要求有哪些？ 素材制作规范要求：排版有层次，色调平衡，画面简洁且兼容美感。 整体：图片内容符合所选模板及场景定位 ，准确的传达信息，突出画面的主题。 排版：尽量通过位置关系（前后、上下、大小等）提升文字层次感。 核心信息区域：视觉焦点位，展示主要信息点，避免字体过多、偏小、偏大，突出利益点。 辅助区域：不放重要信息，可辅助营造氛围感，烘托主体信息。 色调：减少使用强对比色彩，色彩组调保持画面平衡。 图片版权：确保设计用途的版权、人物肖像权；杜绝使用明显政治倾向、色情、暴力、恐怖等图片。 图1 高质量素材样例 图2 高质量素材样例 图3 高质量素材样例 图4 高质量素材样例 图5 高质量素材样例 父主题： 智能模板制作常见问题

各手机厂商视频类智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1 表1 各手机厂商视频类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 视频类模板素材规范 视频 格式 MP4 / MP4 MP4、TS / 尺寸 16：9 16：9 16：9 大小 10M 25M 无限制 标题 1行，17字 1行，17字 2行，30字 正文 3行，69字 3行，69字 2行，69字 按钮 1个，15字 1个，15字 1行，7字 动参能力 √ / √ √ / 各手机厂商视频类智能信息模板终端样例差异 图1 华为终端样例 图2 VIVO终端样例 图3 OPPO终端样例

智能信息模板总体设计规范有哪些 表1 智能信息模板总体设计规范 规范内容 规范要求 注意事项或建议 文字 使用书面语言 文案内容完整 不能有错别字、语法混乱、符号错乱 不标题党、严重夸大商品 不发布过时效的信息或服务 文案与跳转页面相匹配 - 音视频 内容拥有使用版权 优先使用mp4格式，且内容完整流畅 不能出现马赛克/拉伸变形/模糊等 与对应标题、短信、主体匹配 不含有其他平台水印标识 无杂音、无多音轨 - 图片 内容拥有使用版权 符合所选模板及场景定位 单图大小不超2MB 要素从简、扁平化设计 保证清晰美感，有明确主色调，减少使用强对比色彩 不超过3种字体样式（组合情况下不超过2种字体样式） 周围保持18px~24px边距 不出现引导性按钮 元素不宜过多，以简洁为主 为了保证阅读性，最小文字不小于30px 跳转链接 不存在无法打开的链接、恶意网址 不存在不适用PC的页面 落地页与素材相匹配 不违反广告法 核心功能流程支持全流程流畅 无拉伸、收缩、扭曲等变形或者页面不适配的情况 链接必须为https或http开头 链接跳转需跳转到厂商应用下载平台 页面上线后如有问题，将直接下线再另行通知 父主题： 智能信息模板制作规范

各手机厂商智能信息支持能力差异有哪些？ 表1 各手机厂商智能信息支持能力 各手机厂商智能信息支持能力一览表 华为 小米 OPPO VIVO 魅族 点击事件 打开H5 √ √ √ √ √ 打开浏览器 √ √ √ √ √ 打开快应用 √ √ √ √ √ 打开app √ √ √ √ √ 打电话 √ √ × × √ 发短信 √ √ × × √ 发邮件 √ √ × × √ 设置日程 √ √ × × √ 打开地图 √ √ × × √ 弹窗 √ √ × × √ 复制 √ √ × × √ 查看大图 √ √ √ √ × 短链能力 个性化短链 √ √ √ √ √ 群发短链 √ √ √ √ √ 识别类型 短链识别 √ √ √ √ √ 特征码识别 √ × × × × 文本识别 √ × √ √ × 动参能力 文本动参 √ √ √ × × 兜底能力 打开应用市场 √ √ √ √ × 打开H5 √ √ √ √ × 打开浏览器 √ √ √ √ × 打开快应用 √ √ × × × 父主题： 智能模板制作常见问题

各手机厂商电商（多商品类）智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1。 表1 各手机厂商电商（多商品）类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 电商（多商品）类素材规范 图片大小 宽高比1:1，最大大小2M，建议像素192*192 / / / / 主标题 1行，12字 副标题 1行，20字 正文（16:9） 2行，24字 动参能力 √ / / / /

各手机厂商视频图文类和图文视频类智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1 表1 各手机厂商视频图文类和图文视频类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 视频图文模板素材规范 图文视频模板素材规范 视频 格式 MP4，可与图片上下位置互换 / / / / 尺寸 16：9 大小 10M 图片 宽高比21:9，最大大小2M，建议像素1248*704 标题 1行，17字 正文 3行，69字 按钮 1个，15字 动参能力 √ / / / /

各手机厂商长文本智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1表 表1 各手机厂商长文本类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 长文本类素材规范 图片大小 宽高比16:9，最大大小2M，建议像素1120*372 / 宽高比16:9，最大大小2M，建议像素1120*372 / / 标题 1行，15字 1行，15字 正文 18行，350字 18行，350字 动参能力 √ / / / / 各手机厂商长文本类智能信息模板终端样例差异 图1 华为终端样例 图2 OPPO终端样式

各手机厂商智能信息模板应用差异有哪些？ 各手机厂商版式支持差异 表1 各手机厂商版式支持差异 各手机厂商版式支持能力 华为 小米 OPPO VIVO 魅族 支持情况一览表 模板样式 通知 √ √ √ √ × 图文 √ √ √ √ √ 红包 √ √ √ √ × 长文本 √ × √ × × 多图文 √ √ √ √ √ 单卡券/多卡券 √ × × × × 图片轮播 √ × √ √ × 个性化红包 √ × × × × 电商（单商品） √ × √ √ × 横滑 √ × √ × √ 电商（多商品） √ × × × × 视频图文/图文视频 √ × × × × 视频 √ × √ √ × 各手机厂商信箱展示差异 华为终端收件箱列表显示一行，小米、OPPO及VIVO收件箱列表显示两行。收件箱显示两行的终端，智能信息文案尽量用原短信文案，前置利益点。 智能信息短信在短链和签名报备的情况下，会优先推送至主要栏。 图1 华为终端样例 图2 小米终端样例 图3 OPPO终端样例 图4 vivo终端样例 父主题： 智能模板制作常见问题

模板用途/来源、图片、文案问题规范要求有哪些？ 模板用途问题 模板用途区分，规范示范如图1。 图1 模板用途规范样例 模板发送主体问题 模板发送主体要清晰。错误示范如图2所示，其中图片文案均未出现商家主体。正确示范如图3所示，商家主体在图片或文案显眼位置标识。 图2 错误示范样例 图3 正确示范样例 图片素材问题 合格图片：简洁美观重点突出 图4 合格图片样例 图5 合格图片样例 不合格图片：文字与图片元素重叠、图片模糊、小字多看不清、截断、白底 、大片留白区域、周围大片空白 图6 不合格图片样例：文字与图片元素重叠 图7 不合格图片样例：图片模糊、小字多看不清 图8 不合格图片样例：截断 图9 不合格图片样例：白底 、大片留白区域 图10 不合格图片样例：周围大片空白 文案合规问题 图片/文案涉及其他厂商 图11 错误样例：图片/文案涉及其他厂商 文案截断 图12 错误样例：文案截断 不可使用有明显诱导性的按钮（如手指、箭头等） 图13 错误样例：诱导性符号按钮 不可使用具有明显诱导性，且与实际使用场景不符的文案（如小贷类的已到账、待领取等强诱导性字眼） 图14 错误样例：诱导性不实文案/按钮 图14中“到账”与实际使用场景不服且包含手指/箭头等强诱导性符号。 父主题： 智能模板制作常见问题

各手机厂商图片轮播类智能信息模板差异 各手机厂商支持内容的差异 支持情况及规范要求参见表1。 表1 各手机厂商图片轮播类智能信息模板支持内容的差异 品牌 华为 小米 OPPO VIVO 魅族 图片轮播48:65模板制作素材规范 图片大小 宽高比48:65，最大大小2M，最小像素960*1300，建议像素1088*1473 / 宽高比48:65，最大大小2M，最小像素960*1300，建议像素1088*1473 宽高比48:65，最大大小2M，最小像素960*1300，建议像素1088*1473 / 标题 1行，17字 1行，17字 2行，30字 正文 3行，69字 2行，69字 3行，69字 图片轮播16:9模板制作素材规范 图片大小 宽高比16:9，最大大小2M，最小像素1088*612，建议像素1248*704 宽高比16:9，最大大小2M，最小像素1088*612，建议像素1248*704 宽高比16:9，最大大小2M，最小像素1088*612，建议像素1248*704 标题 1行，17字 1行，17字 2行，30字 正文 11行，253字 2行，69字 3行，69字 图片轮播1:1模板制作素材规范 图片大小 宽高比1:1，最大大小2M，最小像素1088*1088，建议像素1088*1088 宽高比1:1，最大大小2M，最小像素1088*1088，建议像素1088*1088 宽高比1:1，最大大小2M，最小像素1088*1088，建议像素1088*1088 标题 1行，17字 1行，17字 2行，30字 正文 11行，253字 2行，69字 3行，69字 动参能力 √ / √ √ / 各手机厂商图片轮播类智能信息模板终端样例差异 图1 华为终端样例 图2 OPPO终端样例 图3 VIVO终端样例

能否通过动态参数指定智能信息模板的图片、跳转链接、标题、内容？ 动态参数的作用是为了方便客户看到个性化内容，目前仅支持标题、文案和链接设置动参，不支持图片的动参。 动态参数的内容要求来源合法或有充分授权，不会出现不正当竞争行为或侵犯第三方的著作权、信息网络传播权等任何合法权益。用户在使用动态参数时应承诺所有素材内容与推送消息内容保持一致，不包含违法和不良信息内容；对于信息内容中人物的肖像权也已获得充分授权、可合法用于展示、介绍、宣传、推广、演示产品、服务、公司或与公司有关的其他事务。 父主题： 其他问题