06 使用指南
文档版本 01
发布日期 2022-02-16
非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传 播。
商标声明
和其他华为商标均为华为技术有限公司的商标。
本文档提及的其他所有商标或注册商标，由各自的所有人拥有。
注意
您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或 特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声 明或保证。
由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文 档中的所有陈述、信息和建议不构成任何明示或暗示的担保。
目 录
1 概述（联通用户专用）...1
2 应用管理...3
2.1 创建应用（联通用户专用）... 3
2.2 授权应用（联通用户专用）... 8
2.3 数据统计（联通用户专用）... 9
3 产品模型（联通用户专用）...10
4 设备注册鉴权（联通用户专用）...14
5 订阅推送（联通用户专用）...22
6 数据上报（联通用户专用）...25
7 命令下发（联通用户专用）...27
8 设备配置更新（联通用户专用）...37
9 设备影子（联通用户专用）...41
10 规则引擎（联通用户专用）... 46
11 群组与标签（联通用户专用）...56
12 设备监控（联通用户专用）... 60
13 远程诊断（联通用户专用）... 68
14 固件升级（联通用户专用）... 71
15 软件升级... 83
15.1 升级指导（联通用户专用）... 83
15.2 设备侧适配开发指导（联通用户专用）... 95
15.3 PCP 协议介绍（联通用户专用）... 112
16 网关与子设备（联通用户专用）... 119
1 概述（联通用户专用）
非联通用户请查看设备接入服务。
物联网平台提供海量设备的接入和管理能力，配合华为云其他产品同时使用，帮助快 速构筑物联网应用，简化海量设备管理复杂性，节省人工操作，提升管理效率。
功能 简介
应用管理 应用可以理解为在物联网平台中为用户的业务划分一个项目空间，当 用户在开发中心、线下环境里完成应用服务器侧的开发、物联网平台 侧的开发以及设备侧的开发后，就需要在控制台上创建应用，将开发 完的应用服务器与真实设备接入到这个项目空间中，实现设备的数据 采集和设备管理。
产品模型 又称Profile，用于定义一款接入设备所具备的属性（如颜色、大小、采 集的数据、可识别的指令或者设备上报的事件等信息），然后通过厂 家、设备类型和设备型号，唯一标识一款设备，便于平台识别。产品 模型可通过开发中心进行无码化开发。
设备注册 鉴权
物联网平台对接入平台的设备进行鉴权认证。待真实设备上电后，设 备可以上报数据到物联网平台，物联网平台根据应用服务器的订阅消 息类型，把消息推送给应用服务器。
订阅推送 订阅：是指应用服务器通过调用物联网平台的API接口，向平台获取发 生变更的设备业务信息（如设备注册、设备数据上报、设备状态等）
和管理信息（软固件升级状态和升级结果）。
推送：是指订阅成功后，物联网平台根据应用服务器订阅的数据类 型，将对应的变更信息推送给指定的URL地址。
数据上报 当设备完成和物联网平台对接后，一旦设备上电，设备基于在设备定 义上的业务逻辑进行数据采集和上报，可以是基于周期或者事件触 发。
命令下发 为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可 向设备下发的命令，应用服务器可以调用物联网平台开放的API接口向 单个设备或批量设备下发命令，或者用户通过物联网平台直接向单个 设备下发命令，配置或修改设备的服务属性值，以实现对设备的远程 控制。
功能 简介 设备配置
更新
物联网平台提供设备配置更新功能，即用户可通过控制台对单个设备 或批量设备的设备属性值进行修改，满足用户频繁、快捷、方便的管 理设备的诉求。
设备影子 设备影子是一个JSON文件，用于存储设备的在线状态、设备最近一次 上报的设备属性、应用服务器期望下发的配置。每个设备有且只有一 个设备影子，设备可以获取和设置设备影子以此来同步状态，这个同 步可以是影子同步给设备，也可以是设备同步给影子。
规则引擎 指用户可以在物联网平台上可以对接入平台的设备设定相应的规则，
在条件满足所设定的规则后，平台会触发相应的动作来满足用户需 求。包含设备联动和数据转发两种类型。
群组与标 签
群组是一系列设备的集合，用户可以对应用下所有设备，根据区域、
类型等不同规则进行分类建立群组，以便处理对海量设备的批量管理 和操作。
物联网平台支持定义不同的标签，并对设备打标签，通过标签，可以 快速筛选设备。
设备监控 提供查看设备详情、设备状态管理、查看报表、查看操作记录、查看 审计日志、告警管理、设备消息跟踪等设备监控与运维能力，提升设 备的可维护性。
远程诊断 支持用户对接入的设备进行远程维护操作，快速定位问题及恢复业 务，减少近端维护引入的高成本。当前支持的远程维护操作包括设备 的运行日志收集、重启模组。
固件升级 用户可以通过OTA的方式对支持LWM2M协议的设备进行固件升级，升 级协议为LWM2M协议。
软件升级 用户可以通过OTA的方式支持对LWM2M协议的设备进行软件升级，升 级协议为PCP协议。
网关与子 设备
物联网平台支持设备直连，也支持设备挂载在网关上，作为网关的子 设备，由网关直连，通过网关进行数据转发。
2 应用管理
2.1 创建应用（联通用户专用）
2.2 授权应用（联通用户专用）
2.3 数据统计（联通用户专用）
2.1 创建应用（联通用户专用）
非联通用户请查看设备接入服务。
应用可以理解为在物联网平台中为用户的业务划分一个项目空间，当用户在开发中 心、线下环境里完成应用服务器侧的开发、物联网平台侧的开发以及设备侧的开发 后，就需要在控制台上创建应用，将开发完的应用服务器与真实设备接入到这个项目 空间中，实现设备的数据采集和设备管理。
遵循华为公有云的子项目概念，物联网平台不再以应用来区分商用场景，建议通过产 品模型或者分组标签来区分商用场景（行业等）。默认一个用户只有一个应用。
创建应用
步骤1 使用华为云帐号，登录物联网平台控制台，点击右上角“进入设备管理服务”（也可 以使用华为云帐号，直接登录https://cn-north-4-iot-sp.huaweicloud.com）。
为保证良好的显示效果和易用性体验，请使用兼容性良好的浏览器，对于浏览器的要 求如下：
浏览器类型 版本要求 分辨率
Internet
Explorer Internet Explorer 11及以上版本 推荐1366 x 768分辨率 Firefox Firefox 51.0~61.0版本
Chrome Google Chrome 58.0~67.0版本
步骤2 用户登录设备管理服务的控制台时，系统自动为用户创建了一个默认应用。由于默认 应用的密钥无法获取，因此如果用户需要使用默认应用，则需要在应用定义里重置应 用密钥。
如果用户需要自己重新创建应用，需要删除默认应用。
步骤3 （若使用默认应用则无需执行此步骤）参考下表按照实际情况填写配置参数。
参数名称 参数说明 基本信息
应用名称 定义用户的应用的名称，应用名称必须为帐号下唯一，且创建后 不可更改。
所属行业 根据用户的应用的行业属性进行选择。
消息跟踪数据授 权
设置物联网平台运营管理员可以跟踪发生故障的设备的权限。
● 打开授权，表示平台管理员在辅助用户进行设备的故障定位 时，可以跟踪设备上报的业务数据，便于快速解决问题。授权 打开的状态下需要设置“授权时效”，可设置“指定时间”或 者“永久有效”。为了保证用户的数据权益，物联网平台运维 管理员跟踪的设备数据保留时间不超过3天。
● 关闭授权，表示平台管理员在辅助用户进行设备的故障定位 时，不能跟踪设备上报的业务数据，可能导致没有足够的信 息，将会降低问题定位效率，建议您授权给平台管理员进行业 务数据的跟踪。
消息推送
参数名称 参数说明 选择协议 推送协议
应用服务器向物联网平台进行消息订阅，物联网平台在推送数据 时可以采用加密的HTTPS协议或者非加密的HTTP协议。推荐采用 HTTPS协议。
● HTTPS方式：表示物联网平台与应用服务器之间采用加密的传 输协议，需要应用服务器侧上传CA证书。
● HTTP方式：表示物联网平台与应用服务器之间采用非加密的 传输协议。此方式的安全性较低，存在物联网平台与应用服务 器之间通信信息泄露风险。
CA证书
创建应用时无需上传CA证书，请创建完应用后根据加载推送证书 上传CA证书。
平台能力
设备数据处理 物联网平台提供设备上报数据的存储能力，用户可以通过“存储 历史数据”的开关进行控制，默认为“打开”状态。
● 打开开关：即物联网平台会对上报数据进行存储，存储时间以 界面显示的存储时间为准。
● 关闭开关：即物联网平台不对上报数据进行存储。
用户可以通过数据转发规则转发到华为云其他云服务上进行存储 和处理。
推送服务 应用服务器向物联网平台订阅设备信息，物联网平台能够向应用 服务器进行消息推送。
其他
应用描述 对该应用的描述。
应用图标 为该应用添加自定义图标。
步骤4 （若使用默认应用则无需执行此步骤）勾选“我已阅读并同意 《个人数据使用条 款》”，单击“确定”，完成创建应用。创建完成后，系统弹出“成功”对话框，显 示应用的基本信息，包含应用ID、应用密钥。
● 请单击“保存密钥至本地”，以保存应用密钥信息，密钥信息在应用详情页内不 可见，请妥善保管。如果遗忘应用密钥时，可在“应用列表”中单击 ，选择
“重置密钥”，或者通过应用详情页内“应用定义 > 安全”，单击“重置”进行 重置密钥。
说明
应用ID和应用密钥用于应用服务器接入物联网平台，如果重置密钥，旧的密钥将不能使 用，您的应用服务器需要更新为新的密钥才能重新接入平台，请谨慎操作。
● 单击“查看应用详情”进入应用详情页，具体功能介绍参照“查看应用”。
● 单击“返回应用列表”，返回到创建应用页。单击“应用列表”中应用的图标，
可直接进入该应用的应用详情页。
----结束
查看应用
创建应用后，用户可根据实际情况查看或者修改应用信息。在“应用列表”中单击应 用，可查看该应用的详细信息。
参数类型 参数说明
基本 可查询应用的基本信息，包括应用名称、应用ID、创建时间以及该应用 所属的行业，应用ID用于应用服务器接入物联网平台。其中用户可根据 实际变更修改应用所属的行业。
安全 ● 可重置密钥，重置后旧密钥自动失效，应用服务器需要更新为新的密 钥才能重新接入物联网平台。
● 可打开或者关闭消息跟踪数据授权开关。
– 打开授权，表示平台管理员在辅助用户进行设备的故障定位时，
可以跟踪设备上报的业务数据，便于快速解决问题。授权打开的 状态下需要设置“授权时效”，可设置“指定时间”或者“永久 有效”。为了保证用户的数据权益，物联网平台运维管理员跟踪 的设备数据保留时间不超过3天。
– 关闭授权，表示平台管理员在辅助用户进行设备的故障定位时，
不能跟踪设备上报的业务数据，可能导致没有足够的信息，将会 降低问题定位效率，建议您授权给平台管理员进行业务数据的跟 踪。
接入 ● 可查询绑定在该应用下的设备与物联网平台进行数据对接的不同协议 所对应的端口信息。
● 可查询绑定在该应用上的应用服务器与物联网平台进行数据对接的端 口信息。
应用和设备接入的域名和接口信息，请在设备接入服务的控制台上获 取。
参数类型 参数说明
消息推送 推送协议是由应用服务器在订阅物联网平台的设备信息时设置的传输协 议来确定的。应用服务器设置的订阅数据推送的传输通道为HTTP时，用 户可以设置采用加密的HTTPS协议或者非加密的HTTP协议进行传输数 据。如果采用HTTPS协议，需要上传CA证书，证书的上传可参考上传
CA证书。
说明如果采用HTTPS协议，应用服务器取消了订阅，则绑定的证书会自动解绑，重新 订阅后，请重新上传CA证书。
其他 用户可以修改应用图标和应用描述。
CA证书加载方法：
步骤1 在应用详情页内“应用定义 > 消息推送”，单击“证书管理”按钮，在弹出的对话框 中单击“添加”按钮。
步骤2 按照表格填写相关信息后，单击“确定”完成证书的加载。
参数名称 参数说明
CA证书 需要提前申请和购买CA证书文件，CA证书由应用服务器侧提供。
说明
调测时可自行制作调测证书，商用时建议更换为商用证书，否则会带来安全风 险。
域名/IP与
端口 物联网平台推送消息到应用服务器的域名或IP地址与端口信息。填写 为订阅接口（“订阅平台业务数据”和“订阅平台管理数据”）里的 callbackurl中对应的域名或IP地址与端口信息。例如：
api.huawei.com:9001或172.0.1.2:8080。
lb昵称 证书加载的LoadBalance对应的昵称，选择默认值：default。
是否检查CNNAME 是否对CA证书的CNNAME进行校验，确保要加载的证书与申请的证书 是完全匹配的。建议打开该开关。
CNNAME “是否检查CNNAME”开关打开时出现。CA证书中携带的证书名称，
请向证书申请人员获取。
支持SNI 默认不勾选，如果接收推送消息的服务器存在多个服务器使用同一个
“IP+端口”，则需要勾选支持SNI，“CNNAME”填写需要接收消息 的服务器的域名地址，以便服务器根据指定的域名携带对应的设备证 书。
使用设备证 书
保持默认值：关闭
----结束
2.2 授权应用（联通用户专用）
非联通用户请查看设备接入服务。
概述
物联网平台作为一个跨行业的通用平台，面向广大的企业用户，支持不同行业、不同 类型的应用接入，对设备访问有严格权限管理，每个用户、应用只能对自己创建的资 源有访问权限，默认不能访问其他用户、应用创建的资源。
访问授权
物联网平台支持在控制台上填写应用ID、授权权限，将设备的管理权限授权给其他应 用，包括同一个用户下的不同应用之间的授权、两用户下（如用户A开通设备接入服 务，用户B开通设备管理服务）的不同应用之间授权，且两应用之间可以相互授权。可 以授予访问资源部分权限（如只有查询权限）或整体赋权如管理角色(如设备管理的增 删改查功能)。
授权不会传递，应用A授权给应用B，应用B授权给应用C，不等同于应用C获取了应用A 的授权。
例如：用户将B应用授权给A应用管理，进行授权操作时可选择授权查询权限或者编辑 权限，如果是授权编辑权限，则A应用可以管理B应用下的设备，A应用具备和B应用一 样的设备管理权限，但不允许将B应用下的设备挂到A应用下的群组中；如果是查询权 限，则A应用仅可以查询B应用下的设备。
解除授权
可以收回资源访问权限，即解除授权。
操作步骤
以应用A授权给应用B为例，具体操作步骤如下：
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 单击A应用，进入应用详情。
步骤3 单击“授权应用”页签。
步骤4 选择“授权应用列表”，在列表中可以查看或删除已经授权过的应用。
步骤5 单击“授权操作”，在弹出的“授权操作”对话框选择B应用。如果是其他用户，则选 择“其他租户的应用”，并且填写B应用ID、授权权限，其中授权权限为“编辑”时，
才可以操作授权应用下的设备（编辑的对象是应用下的设备资源，即对设备管理节点 下进行操作，无法编辑授权应用详情中的信息）。
说明
应用ID的获取方式：1、创建新应用成功时，系统会自动返回应用ID。2、对于已经创建的应 用，可以在应用详情的“应用定义”页签中查看应用ID。
步骤6 单击“授权”，完成应用A授权给应用B的操作。
● 在B应用详情的“被授权应用”中可以查看A应用的基本信息。如果应用A和B分别 属于不同用户，还可以登录B应用对应的控制台，在“应用管理 > 被授权应用”页 签中查看到A应用的基本信息。
● 如果应用A和B分别属于不同用户，在A应用详情的“授权应用 > 授权租户列表”
中可以看到B应用所属的用户名称。单击 ，可以解除租户授权，此时该租户下 所有被授权的应用都将解除授权，并从“授权应用列表”中移除。
步骤7 被授权的应用可以通过控制台查看和操作授权应用下的所有设备。
----结束
2.3 数据统计（联通用户专用）
非联通用户请查看设备接入服务。
在控制台上，应用详情中单击“数据统计”，可查看该应用与物联网平台通信交互情 况统计，单击每一行统计项右侧的“查看”，可以查看详细的报表统计信息。
统计名 称
统计说明 数据刷新
周期 数据上
报统计 统计最近72小时直连设备上报业务数据的成功和失败次数
（不含设备状态变更的数据，如设备上线）。上报数据类型 例如当前温度、电量等。
● 统计指标为次数，包含“总数”、“成功数”、“失败 数”和“成功率”。
● 统计维度为时间。平台提供对统计指标和维度的筛选功 能。
30分钟
命令下 发统计
统计来自物联网平台或第三方应用向设备发出的控制命令。
● 统计指标为次数，包含“总数”、“成功数”、“失败 数”和“成功率”。
● 统计维度为时间。平台提供对统计指标和维度的筛选功 能。
30分钟
消息流 控统计
平台对同一个应用下的所有设备在同一时间上报的消息量进 行控制，以防止在终端设备异常或受到外部攻击时，设备在 短时间内可能上报大量的消息，造成系统性能下降或瘫痪。
记录最近24小时的数据。
手动刷新
3 产品模型（联通用户专用）
非联通用户请查看设备接入服务。
概述
产品模型（也称Profile）用于描述设备具备的能力和特性。开发者通过定义Profile，
在物联网平台构建一款设备的抽象模型，使平台理解该款设备支持的服务、属性、命 令等信息，如颜色、开关等。当定义完一款产品模型后，在进行设备注册时，就可以 选择已在控制台上导入的产品模型。
Profile包括产品信息、服务能力、维护能力三部分：
● 产品信息
描述一款设备的基本信息，包括厂商ID、厂商名称、设备类型、型号、协议类 型。其中厂商ID和型号唯一标识一款产品。
例如：水表的厂商名称为“HZYB”，厂商ID为“TestUtf8ManuId”，设备类型 为“WaterMeter”，型号为“NBIoTDevice”，协议类型为“CoAP”。
● 服务能力
描述设备具备的业务能力。将设备业务能力拆分成若干个服务后，再定义每个服 务具备的属性、命令以及命令的参数。
以水表为例，水表具有多种能力，如上报水流、告警、电量、连接等各种数据，
并且能够接受服务器下发的各种命令。Profile文件在描述水表的能力时，可以将
服务名 描述 基础（WaterMeterBasi c）
用于定义水表上报的水流量、水温、水压等参数，如果需 要命令控制或修改这些参数，还需要定义命令的参数。
告警（WaterMeterAlar m）
用于定义水表需要上报的各种告警场景的数据，必要的话 需要定义命令。
电池（Battery） 定义水表的电压、电流强度等数据。
传输规则（DeliverySchedul e）
定义水表的一些传输规则，必要的话需要定义命令。
连接（Connectivity） 定义水表连接参数。
注：具体定义几个服务是非常灵活的，如上面的例子可以将告警服务拆分成水压 告警服务和流量告警服务，也可以将告警服务合入到水表基础服务中。
● 维护能力
描述设备具备的维护能力，包括固件升级、软件升级、配置更新。
关于Profile文件的规范、含义和样例等，可参考如何离线开发？
开发产品模型
Profile的开发手段有在线开发和离线开发两种，我们推荐使用开发中心在线开发。
● 在线开发：即在开发中心上，通过界面操作进行开发Profile，开发完成后可以下 载，并发布到产品中心。如何在线开发？
● 离线开发：是指开发者通过了解Profile格式规范，在本地进行开发、打包。如何 离线开发？
新增产品模型
Profile开发完成并测试验证后，可以将profile文件导入到控制台上使用，有三种导入 方式：
● 产品中心导入：在开发中心上完成profile的定义并发布到产品中心。
● 本地导入：指线下完成profile的开发，通过上传profile包的方式导入。
注：通过本地导入的profile不含编解码插件，如果设备上报采用的是二进制码 流，请使用产品中心导入的方式。
● 手动创建：手动创建一个产品（支持CoAP/LWM2M、MQTT或LoRaWAN），不 定义设备属性（不需要开发profile及编解码插件），仅透传数据，不解析数据
（透传模式具体请参考6 数据上报（联通用户专用））。如使用手动创建的产品 模型，建议仅开通设备接入服务即可。
说明
● 当协议类型选择LoRaWAN时，无法注册为普通设备，仅能注册为LoRaServer的子设备。
● 导入产品模型后，就无法对已导入产品模型的产品信息和服务能力进行修改，例如修改协议 类型、新增一个服务等。可以通过设备配置更新、设备影子对设备服务属性值进行修改，通 过界面修改OM维护能力。
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 单击左下角 ，选择“产品模型”，单击“新增产品模型”。
步骤3 产品模型可通过从产品中心导入和从本地导入两种方式。
● 从产品中心导入：
a. 选择“从产品中心导入”，进入到产品中心页面。
▪
导入自有产品：产品中心默认显示自有产品列表，可通过产品名称或者 设备类型搜索产品。▪
导入第三方公开产品：“产品范围”选择“第三方公开”，可通过产品 名称、设备类型或者厂商名称搜索产品。▪
导入第三方私有产品：单击页面右上角“第三方私有产品”，在弹出的 窗口中输入产品验证码，该验证码由设备厂商提供。b. 在搜索的产品模型列表中单击需要导入的产品名称。
● 从本地导入：
a. 选择“本地导入”进入到本地导入产品的页面。
b. 在弹出的窗口中输入产品名称，并上传资源文件。
c. 单击“确定”，等待导入完成。
步骤4 在“产品模型”页面查看导入结果。
● 导入失败：可在“失败原因”中查看导入失败的原因，用户可根据失败原因定位 错误。
● 导入成功：可单击“详情”，查看产品模型详情。
关于自定义topic，每个产品模型最多可以自定义10个，只有MQTT协议接入的设备支 持自定义，参数信息配置如下：
● 设备操作权限：
– 发布： 设备侧消息上报时，可按配置中自定义的topic进行消息上报；数据流 转时，设备消息中会携带topic参数标识该消息从哪个topic上报。
– 订阅：设备侧消息下发时，可在消息内容中指定此消息下发使用哪个topic；
消息发往设备时，可以根据指定的topic下发。
– 发布和订阅：同时具备发布和订阅的权限。
● topic名称：自定义即可。支持英文字母、数字、下划线，+和#（仅权限是订阅时 支持），长度限制64。
● 描述：关于该topic的描述。
说明
– 如果还未使用该产品模型注册设备，则可以删除该产品模型。
– 如果已使用该产品模型注册过设备，则无法删除该产品模型。
----结束
4 设备注册鉴权（联通用户专用）
非联通用户请查看设备接入服务。
概述
设备注册鉴权是指物联网平台对接入平台的设备进行注册鉴权。对于不同接入方式的 设备，注册鉴权方式不同。
接入类型 注册鉴权方式
使用LWM2M/CoAP 协议接入的设备
在设备接入物联网平台前，用户通过应用服务器调用注册设 备（验证码方式）接口或通过控制台在物联网平台注册设 备，并把设备的唯一标识码nodeId（如IMEI）设置为设备接 入平台的验证码。在设备接入物联网平台时携带设备唯一标 识，完成设备的接入鉴权。
当采用DTLS/DTLS+传输层安全协议接入时，即设备为安全设 备时，通过密钥进行设备和物联网平台之间的传输通道安全 加密。如图所示。
集成Agent Lite
SDK的设备 在设备接入物联网平台前，用户通过应用服务器调用注册设 备（验证码方式）接口或通过控制台在物联网平台注册设 备，并把设备的唯一标识码nodeId（如IMEI）设置为设备接 入平台的验证码，平台返回设备ID。当设备上电时，携带 nodeId等进行平台绑定，并返回设备ID和密钥。当绑定后设 备重新登录时，携带设备ID和密钥完成网关的接入鉴权。如 图所示。
如果设备是网关，网关下有子设备，则当网关接入物联网平 台后，在网关上通过调用Agent Lite的添加非直连设备接口，
完成子设备的接入，具体请参见16 网关与子设备（联通用户 专用）。
使用原生MQTT协 议接入的设备
在设备接入物联网平台前，用户通过应用服务调用注册设备
（密码方式）接口或通过控制台在物联网平台注册设备，获 取设备ID和密钥，并把设备ID和密钥烧录到设备中。在设备 接入物联网平台时携带设备ID和密钥、或者nodeId和密钥，
业务流程
使用LWM2M/CoAP协议接入的注册鉴权流程
1. 通过调用注册接口向物联网平台发送注册请求或者在控制台上注册设备。
2~3. 物联网平台向设备分配全局唯一的预置密钥，并返回timeout。
说明
● 预置密钥可以在注册设备时自定义，如果没有定义，平台将自动分配预置密钥。
● timeout是指超时时间，若设备在有效时间未接入物联网平台，则平台会删除该设备的注册 信息。
4. 用户将预置密钥烧录到设备硬件或软固件中。
5. 设备上电后，携带设备唯一标识码nodeId（如IMEI）和预置密钥发起接入鉴权请 求。
6~7. 平台验证通过后，返回成功响应，设备连接物联网平台成功。
集成Agent Lite SDK的注册鉴权流程
1. 通过调用注册接口向物联网平台发送注册请求或者在控制台上注册设备。
2. 物联网平台向设备分配全局唯一的设备ID （deviceId），并返回密钥和timeout。
说明
timeout是指超时时间，若设备在有效时间内未接入物联网平台，则平台会删除该设备的注册信 息。
3~4. 设备第一次上电接入物联网平台时需要进行绑定操作，从而将设备与平台进行关 联。设备携带nodeId和密钥进行平台绑定，平台返回设备ID、MQTT登录密钥、
AppId、MQTT设备侧接入地址。
5~6. 绑定后设备重新登录时，携带设备ID、mqtt接入密钥、AppId、平台HTTPS地 址、MQTT设备侧接入地址，完成设备的接入鉴权。具体请参见Agent Lite SDK 使用 指南（C）、Agent Lite SDK 使用指南（JAVA）、Agent Lite SDK 使用指南
（Android）。
如果设备是网关，网关下有子设备，则当网关接入物联网平台后，用户在网关上通过 调用Agent Lite的“添加非直连设备”接口，完成子设备的接入。
使用原生MQTT协议接入的注册鉴权流程
1. 通过调用注册接口向物联网平台发送注册请求或者在控制台上注册设备。
说明
注册时需要填写设备的nodeId，通常使用MAC地址，Serial No或IMEI作为nodeId。
2. 物联网平台向设备分配全局唯一的设备ID （deviceId）和密钥（secret）。
说明
密钥可以在注册设备时自定义，如果没有定义，平台将自动分配密钥。
3. 用户将设备ID （deviceId）和密钥（secret）烧录到设备硬件或软固件中。
4. 设备上电后，携带设备ID （deviceId）和密钥（secret）或者携带nodeId和密钥
（secret）发起接入鉴权请求。
5. 平台验证通过后，返回成功响应，设备连接物联网平台成功。
单个设备注册
物联网平台支持通过应用服务器调用“注册设备（验证码方式）”/“注册设备（密码 方式）”接口、或者在控制台上进行单个设备注册。控制台上注册方式如下：
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 单击左下角 ，选择“ 设备 > 设备注册”。
步骤3 选择页签“单个注册”，单击右上角“创建”，按照如下表格填写参数后，单击“确 定”。
参数名称 配置原则
选择产品 选择要注册的产品名称。
只有在“产品模型”里定义了产品，此处才可以选择具体的产 品。如没有，请先上传或直接创建产品模型。
设备标识码
(nodeId) 设备唯一物理标识，如IMEI、MAC地址等，用于设备在接入物 联网平台时携带该标识信息完成接入鉴权。
● 原生MQTT设备：通过注册成功后生成的“设备ID”（与设 备标识码一一对应）和“密钥”接入平台。
● NB-IoT设备、集成Agent Lite SDK的设备：设备通过注册时 填写的“设备标识码”和“密钥”接入平台。
设备 ID(deviceId) 由平台生成的设备唯一标识，其生成规则为“产品ID” +
“_” + “设备识别码”。
● 不需要用户手动填写，由产品和设备识别码按照规则生成。
● 对于原生MQTT设备，接入平台时携带设备ID和密钥接入鉴
参数名称 配置原则
密钥 当“设备认证类型”选择“密钥”时填写。
● 设备密钥，可自定义，不填写系统自动生成
● NB-IoT设备密钥只支持十六进制，用于设备和物联网平台 之间的传输通道安全加密
● 注册完后可重置密钥。
确认密钥 当“设备认证类型”为“密钥”时，再次填写密钥。
步骤4 （可选）注册设备成功，请保存好设备ID和密钥，用于设备接入平台认证。
----结束
批量设备注册
物联网平台支持在控制台上进行批量设备注册。控制台上注册方式如下：
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 单击左下角 ，选择“设备 > 设备注册” 。
步骤3 选择页签“批量注册”，单击右上角“创建”，填写“任务名称”，“选择产品”，
并上传批量注册文件，单击“提交”，完成设备的批量注册。
参数名称 配置原则
选择产品 选择要注册的产品名称。
只有在“产品模型”里定义了产品，此处才可以选择具体的产 品。如没有，请先上传或直接创建产品模型。
nodeId(设备标识
码) 设备唯一物理标识，如IMEI、MAC地址等，用于设备在接入物 联网平台时携带该标识信息完成接入鉴权。
● 原生MQTT设备：通过注册成功后生成的“设备ID”（与设 备标识码一一对应）和“密钥”接入平台。
● NB-IoT设备、集成Agent Lite SDK的设备：设备通过注册时 填写的“设备识别码”和“密钥”接入平台。
secret(密钥) ● 设备密钥，可自定义，不填写系统自动生成
● NB-IoT设备密钥只支持十六进制，用于设备和物联网平台 之间的传输通道安全加密
● 注册完后可重置密钥。
步骤4 （可选）批量注册执行成功，如果是原生MQTT设备注册，请单击批量任务一行，进 入任务的“执行详情”，点击“导出”按钮，保存好设备ID和密钥，用于原生MQTT 设备接入平台。
重置密钥
登录控制台，进入具体的设备详情，选择“设置”页签。
● 重置密钥：密钥用于设备采用原生MQTT、NB-IoT设备、集成Agent Lite SDK的 设备接入接入物联网平台的鉴权认证。重置密钥后，需要将新的密钥信息更新到 设备中，设备重新发起注册时，携带新的密钥进行认证。
相关 API 接口
● 注册设备（验证码方式）
● 注册设备（密码方式）
● 刷新设备密钥
5 订阅推送（联通用户专用）
非联通用户请查看设备接入服务。
概述
订阅：是指应用服务器通过调用物联网平台的“订阅平台业务数据”和“订阅平台管 理数据”接口，向平台获取发生变更的设备业务信息（如设备注册、设备数据上报、
设备状态等）和管理信息（软固件升级状态和升级结果）。
推送：是指订阅成功后，物联网平台根据应用服务器订阅的数据类型，将对应的变更 信息（推送的通知内容可参考推送通知）推送给指定的URL地址，也称为回调地址
（什么是回调地址？）。如果应用服务器没有订阅该类型的数据通知，即使数据发生 了变更也不会进行推送。物联网平台进行数据推送时，数据格式为JSON格式，推送协 议可以采用HTTP或HTTPS协议，其中HTTPS协议为加密传输协议，需要进行安全认 证，更加安全，推荐使用。
订阅推送的示意图如下图所示：
应用服务器使用HTTPS协议调用API接口进行订阅时，应用服务器需要校验物联网平台 的真实性，需要在应用服务器需要加载CA证书，该证书由物联网平台提供，下载证书 文件并解压，在“Northbound API > code”中，根据具体的编程语言进行获取。
物联网平台采用HTTPS协议向应用服务器进行消息推送时，物联网平台需要校验应用 服务器的真实性，需要在物联网平台上加载CA证书，该证书由应用服务器侧提供（调 测时可自行制作调测证书，商用时建议更换为商用证书，否则会带来安全风险）。
用服务器进行推送重试，缓存时间超时后如果还未推送成功，物联网平台不再进行推 送重试。在消息缓存时间内，物联网平台重试推送失败的次数达到10次后，会将该推 送的URL地址设置为无效，并按照轮询的方式，轮询探测所有失败URL有效性检，如果 恢复，则会重新设置该URL为有效。您可以登录设备管理服务控制台的“应用管理 >
应用列表 > 应用详情 > 服务设置”中的“订阅推送服务（HTTP/HTTPS）”查看推送 URL的状态。
说明
只有在创建应用时打开“存储历史数据”开关的情况下（默认为打开），才能进行推送。如果平 台不存储数据，直接透传的情况是不能进行消息推送的。
如何进行数据订阅
应用服务器接入到设备管理服务后，通过调用API接口或者集成SDK进行数据订阅。
● 通过API接口进行数据订阅请参考API开发指导。
● 通过集成SDK进行数据订阅请参考SDK开发指南。
说明
上面的操作样例是基于开发中心的环境进行的开发调测，在商用时，需要将应用服务器对接平台 的信息修改为设备管理服务的接入信息，并重新进行数据订阅。
● BASE_URL：更改为“iot-api.cn-north-4.myhuaweicloud.com（北京4）”。
● APPID和SECRET：更改为在设备管理服务控制台中创建应用时分配的“应用ID”和“应用密 钥”。如果使用默认的应用，请通过“应用详情 > 应用定义”中重置“应用密钥”。
加载推送证书
应用服务器订阅消息成功后，设备的数据和状态发生变更时，物联网平台会向应用服 务器进行消息推送。采用HTTPS协议进行推送时，请确保已经完成了消息订阅的操作 后，再加载CA证书。
● 如果应用服务器取消了订阅后再重新订阅（URL不变），需要在物联网平台上重 新上传CA证书。
● 如果应用服务器新增了订阅类型（新增URL），需要在物联网平台上加载与该URL 对应的CA证书。即使新增URL使用的CA证书与原来推送的URL使用相同的证书，
也需要重新上传CA证书。
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 选择“应用管理 > 应用列表”界面，在“我的应用”页面点击创建的应用。
步骤3 在“应用定义”页签的“消息推送”功能中，单击“证书管理”按钮，上传对应的证 书文件。
步骤4 单击“添加”按钮，按照下表填写相关信息后，单击“确定”完成证书的加载。
参数名称 参数说明
CA证书 需要提前申请和购买CA证书文件，CA证书由应用服务器侧提供。
说明
调测时可自行制作调测证书，商用时建议更换为商用证书，否则会带来安全风 险。
参数名称 参数说明 域名/IP与
端口 物联网平台推送消息到应用服务器的域名或IP地址与端口信息。填写 为订阅接口（“订阅平台业务数据”和“订阅平台管理数据”）里的 callbackurl中对应的域名或IP地址与端口信息。例如：
api.huawei.com:9001或172.0.1.2:8080。
lb昵称 证书加载的LoadBalance对应的昵称，选择默认值：default。
是否检查CNNAME 是否对CA证书的CNNAME进行校验，确保要加载的证书与申请的证书 是完全匹配的。建议打开该开关。
CNNAME “是否检查CNNAME”开关打开时出现。CA证书中携带的证书名称，
请向证书申请人员获取。
支持SNI 默认不勾选，如果接收推送消息的服务器存在多个服务器使用同一个
“IP+端口”，则需要勾选支持SNI，“CNNAME”填写需要接收消息 的服务器的域名地址，以便服务器根据指定的域名携带对应的设备证 书。
使用设备证 书
保持默认值：关闭
----结束
常见问题
订阅推送业务热点咨询问题如下，更多咨询问题请点击查看更多。
● 如何获取证书？
● 调用订阅接口时，回调地址如何获取？
● 回调地址可以使用域名吗？
● 订阅后消息推送失败，例如提示503如何处理？
● 为什么设备上报一条数据后应用服务器会收到多条推送？
相关 API 接口
● 订阅平台业务数据
● 订阅平台管理数据
● 查询单个订阅
● 批量查询订阅
● 删除单个订阅
● 批量删除订阅
6 数据上报（联通用户专用）
非联通用户请查看设备接入服务。
概述
当设备完成和物联网平台对接后，一旦设备上电，设备基于在设备上定义的业务逻辑 进行数据采集和上报，可以是基于周期或者事件触发。设备可通过以下方式发送数据 到物联网平台：
● 设备消息上报：设备可以通过消息上报接口将设备的自定义数据上报到平台，平 台对设备上报的消息不进行解析和存储，通过数据转发规则转发到华为云其他云 服务上进行存储和处理，然后通过其他云服务的控制台或者API接口进行进一步的 数据处理。
● 设备原始数据（二进制）上报：设备可以通过二进制上报接口上报设备的原始码 流，平台通过编解码插件将设备原始数据解析为产品模型定义的JSON格式，解析 后的数据上报给设备管理服务进行相关业务处理。
● 设备属性上报：设备通过属性上报接口，将产品模型中定义的属性数据上报给平 台，平台解析后的数据上报给设备管理服务进行相关业务处理。
● 网关批量属性上报：网关设备将批量设备的数据一次性上报到平台，平台解析后 的数据上报给设备管理服务进行相关业务处理。
说明
CoAP协议接入的设备考虑到功耗和带宽的影响，当前只支持设备上报原始的二进制码流，
由平台根据编解码插件，将码流转换为产品模型中定义的JSON格式数据后，再进行后续处 理。
查看历史数据
如果物联网平台在创建应用时开启了“存储历史数据”功能，则可以在控制台上查看 设备上报的历史数据。
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 在设备列表中，单击具体的设备进入到设备的详情页面。
步骤3 在“历史数据”页签中，可以根据设备的服务、属性、时间段进行过滤历史数据，并 提供对应的历史数据报表展示。
另外，界面上还支持查看全量的所有服务的历史数据，并支持导出历史数据。
----结束
相关 API 接口
● 查询设备历史数据
● 查询设备服务能力
相关设备侧 MQTT 接口
● 设备消息上报
● 网关批量设备属性上报
7 命令下发（联通用户专用）
非联通用户请查看设备接入服务。
概述
为能有效地对设备进行管理，设备的产品模型中定义了物联网平台可向设备下发的命 令，应用服务器可以调用物联网平台开放的API接口向单个设备或批量设备下发命令，
或者用户通过物联网平台直接向单个设备下发命令，以实现对设备的远程控制。
物联网平台有两种命令下发机制，如下表所示。
命令 下发 机制
定义 适用场景 LWM2M/
CoAP协议 设备
集成Agent Lite SDK设 备/原生MQTT设备
立即 下发
不管设备是否在线，
平台收到命令后立即 下发给设备。如果设 备不在线或者设备没 收到指令则下发失 败。支持给本应用的 设备和被授予权限的 其它应用的设备下发 命令。
立即下发适合对命 令实时性有要求的 场景，比如路灯开 关灯，燃气表开关 阀。使用立即下发 时，命令下发的时 机需要由应用服务 器来保证。
建议用户 使用缓存 下发模 式，工作 模式设置为PSM模 式（系统 默认 值）。
如需使用 立即下发 模式（工 作模式设置为DRX 或eDRX模 式），需 要在设备 上报数据 后立即下 发命令才 能成功。
适用
命令 下发 机制
定义 适用场景 LWM2M/
CoAP协议 设备
集成Agent Lite SDK设 备/原生MQTT设备
缓存 下发
物联网平台在收到命 令后先缓存，等设备 上线或者设备上报数 据时再下发给设备，
如果单个设备存在多 条缓存命令，则进行 排队串行下发。支持 给本应用的设备和被 授予权限的其它应用 的设备下发命令。
缓存下发适合对命 令实时性要求不高 的场景，比如配置 水表的参数。
适用。工 作模式设置为PSM 模式（系 统默认 值）。
不适用
业务流程
LWM2M/CoAP协议设备场景
物联网平台提供立即下发和缓存下发两种机制。应用服务器向物联网平台下发命令 时，携带参数expireTime（简称TTL，表示最大缓存时间）。如果不带expireTime，则 默认expireTime为48小时。
● expireTime=0：命令立即下发。
● expireTime>0：命令缓存下发。
图7-1 命令立即下发流程
1. 应用调用创建设备命令接口，下发请求到物联网平台，携带expireTime参数为0。
消息样例如下：
Method: POST
request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands Header:
"app_key: ******"
"Authorization:Bearer******"
Content-Type:application/json Body:
{ "deviceId": "********", "command": {
"serviceId": "Brightness", "method": "SET_DEVICE_LEVEL", "paras": {
"value": "1", }
}, "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl", "expireTime": 0,
"maxRetransmit": 1 }
2. 物联网平台调用编解码插件对命令请求进行编码后，会通过LWM2M协议定义的 设备管理和服务实现接口的Execute操作下发命令，消息体为二进制格式。
3. 物联网平台向应用返回201 Created，携带命令状态为SENT。（如果设备不在线 或者设备没收到指令则下发失败，命令状态为FAIL）
4. 设备收到命令后返回ACK响应。
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口 推送消息给应用，携带命令状态为DELIVERED。消息样例如下：
Method: POST request:
Body:
{ "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba3", "result": {
"resultCode": "DELIVERED", "resultDetail": null }}
6. 设备执行命令后通过205 Content响应返回命令执行结果。
7. 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响 应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为
SUCCESSFUL。消息样例如下：
Method: POST request:
Body:
{ "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": {
"resultCode": "SUCCESSFUL", "resultDetail": null
}}
图7-2 命令缓存下发流程
1. 应用调用创建设备命令接口，下发请求到物联网平台，携带expireTime参数大于 0。
2. 物联网平台将命令写入缓存队列，并上报201 Created，携带命令状态为
PENDING。
3. 设备上线或设备上报数据到平台。
4. 物联网平台调用编解码插件对命令请求进行编码后，根据协议规范下发命令给设 备。
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口 推送消息给应用，携带命令状态为SENT。
6. 后续流程请参考“命令立即下发”的步骤4到步骤7。
集成Agent Lite SDK设备/原生MQTT设备场景
对于集成Agent Lite SDK设备/原生MQTT设备，物联网平台只支持直接下发模式，设 备不在线时命令下发失败。
1. 应用调用设备服务调用接口，下发请求到物联网平台。消息样例如下：
Method: POST
request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands Header:
"app_key: ******"
"Authorization:Bearer******"
Content-Type:application/json Body:
{ "deviceId": "********", "command": {
"serviceId": "Brightness", "method": "SET_DEVICE_LEVEL", "paras": {
"value": "1", }
}, "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl", "expireTime": 0,
"maxRetransmit": 1 }
2. 物联网平台根据协议规范下发命令给设备。
MQTT设备必须先订阅平台命令下发接口对应的Topic才能收到平台下发的命令，
消息样例如下：
{ "msgType": "cloudReq",
"serviceId": "Brightness",
"mid": 2016,
"cmd": "SET_DEVICE_LEVEL",
"paras": { "value": "1"
} }
5. 若应用下发命令时携带了"callbackUrl"，物联网平台通过命令状态变化通知接口 推送消息给应用，携带命令状态为DELIVERED。消息样例如下：
Method: POST request:
Body:
{ "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": {
"resultCode": "DELIVERED", "resultDetail": null }}
6. 设备执行命令后通过设备命令响应通知接口返回命令执行结果，消息样例如下：
response: Status Code: 200 OK
7. 若应用下发命令时携带了"callbackUrl"，物联网平台会调用编解码插件对设备响 应进行解码，然后通过命令状态变化通知接口推送消息给应用，携带命令状态为
SUCCESSFUL。消息样例如下：
Method: POST request:
Body:
{ "deviceId": "6543214c-72bb-4131-9e14-fad974123456", "commandId": "108a9c71462a48e09426e06e844d47ba", "result": {
"resultCode": "SUCCESSFUL", "resultDetail": null
}}
单个设备命令下发
LWM2M/CoAP协议设备
两种方式创建单个NB-IoT设备的命令下发：
● 调用创建设备命令接口。
● 在控制台上创建命令下发，操作步骤如下。
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 在设备列表中，单击具体的设备进入到设备的详情页面。
步骤3 在“命令”页签中，点击右上角“命令下发”，在弹出的窗口中选择需要下发的命令 并设置命令参数。
说明
● 仅NB-IoT设备支持通过控制台进行下发命令操作。
● 设备支持的命令，需要由产品模型定义后，才能在此进行命令下发操作。
● 下发命令的参数中，带“*”的参数为必选配置项，选择不同的命令，界面所呈现的参数不 同。
步骤4 在界面上，展示通过界面或“创建设备命令”接口给设备下发的历史命令列表，通过 该功能可以详细查看命令下发任务的创建时间、平台发送命令的时间、送达的时间、
发送的状态等信息，便于用户了解命令的命令执行状态说明。
----结束
同时，还支持通过调用相关API接口查询、修改、撤销设备命令等操作，如下表所示。
API接口 功能 查询设备
命令
应用服务器向设备下发命令后，可调用此接口在物联网平台查询下发命 令的状态及内容信息，以了解命令的执行情况。
修改设备 命令
应用服务器向设备下发命令后，如果由于命令排队、设备不在线等原 因，物联网平台还未把命令下发给设备执行，此时应用服务器可调用此 接口修改该命令的状态信息。当前仅支持把命令状态修改为CANCELED 状态，即撤销命令的执行。
创建设备 命令撤销 任务
应用服务器向设备下发命令后，如果由于命令排队、设备不在线等原 因，物联网平台还未把命令下发给设备执行（PENDING状态），此时 应用服务器可调用此接口撤销指定设备的所有未下发的命令，对于已下 发成功的命令不可撤销。
查询设备 命令撤销 任务
应用服务器创建了设备命令撤销任务后，可调用此接口查询设备命令撤 销任务的详细信息和执行状态，以了解撤销任务的执行情况。
集成Agent Lite SDK设备/原生MQTT设备 通过调用设备服务调用接口，向设备下发命令。
支持通过控制台设备详情里的“命令”页签，查看给设备下发的历史命令列表，可以 详细查看命令下发任务的创建时间、平台发送命令的时间、送达的时间、发送的状态 等信息，便于用户了解命令的执行状态。
当前不支持通过API接口进行历史命令下发任务的查询。
批量设备命令下发
当前物联网平台仅支持对批量NB-IoT设备进行相同命令的下发。应用服务器可以调用 创建批量任务接口，对批量设备下发控制指令。
命令执行状态说明
命令执行状态以及状态变化机制如下所示。
命令执行状 态
说明
等待（PENDING
）
● NB-IoT设备采用缓存下发模式下发命令时，如果设备未上报数 据，物联网平台会将命令进行缓存，此时任务状态为“等待”状 态。
● NB-IoT设备采用立即下发模式下发命令时，无此状态。
● MQTT设备下发命时令，无此状态。
超期（EXPIRED
）
● NB-IoT设备采用缓存下发模式下发命令时，如果在设置的超期时 间内，物联网平台未将命令下发给设备，则状态变更为“超 期”。超期时间会根据应用侧接口中携带的expireTime为准，如 果未携带，默认48h。
● NB-IoT设备采用立即下发模式下发命令时，无此状态。
● MQTT设备下发命时令，无此状态。
取消（CANCELE D）
如果命令下发任务为“等待”状态时，用户人工取消了命令下发任 务，则任务状态变更为“取消”。
命令执行状 态
说明
已发送（SENT） ● NB-IoT设备采用缓存下发模式下发命令时，设备上报数据，物联 网平台会将缓存的命令发送给设备，此时状态会由“等待”变为
“已发送”。
● NB-IoT设备采用立即下发模式下发命令时，如果设备在线，状态 为“已发送”。
● MQTT设备下发命时令，如果设备在线，状态为“已发送”。
超时（TIMEOUT
）
NB-IoT设备收到命令后，物联网平台在180秒内未收到设备反馈的收 到命令响应，此时状态会变为“超时”。MQTT设备无此状态。
已送达（DELIVERE D）
物联网平台收到设备反馈的已收到下发命令响应后，状态变为“已 送达”。
成功（SUCCESSF UL）
如果设备在执行完命令后，会给物联网平台反馈命令执行成功的结 果，将任务状态变更为“成功”。
失败（FAIL） ● 如果设备在执行完命令后，会给物联网平台反馈命令执行失败的 结果，将任务状态变更为“失败”。
● NB-IoT设备采用立即下发模式下发命令时，如果设备离线，状态 为“失败”。
● MQTT设备下发命令时，如果设备离线，状态为“失败”。
相关 API 接口
● 创建设备命令
● 设备服务调用
● 查询设备服务能力
● 查询设备命令
● 修改设备命令
● 创建设备命令撤销任务
● 查询设备命令撤销任务
● 创建批量任务
● 查询指定批量任务信息
● 查询批量任务的子任务信息
8 设备配置更新（联通用户专用）
非联通用户请查看设备接入服务。
概述
物联网平台提供设备配置更新功能，即用户可通过控制台对单个设备或批量设备的设 备属性值进行修改，满足用户频繁、快捷、方便的管理设备的诉求。比如，某路灯最 初设置温度属性达到A摄氏度时上报告警，用户需要修改该属性值为B摄氏度，即可修 改其配置文件，然后通过控制台上传到物联网平台，以实现配置更新。
● 针对LWM2M协议设备的设备配置更新，物联网平台提供了设备影子功能，将修 改设备的属性信息存储在设备影子中，待设备上线或上报数据时，将修改的设备 属性值同步给设备，从而完成设备属性的修改。
● 针对原生MQTT协议接入或集成Agent Lite SDK的设备，物联网平台直接配置更新 下发，修改设备的设备属性值。
说明
物联网平台第一次给设备下发配置更新，如果当前的配置文件还没有下发给设备前，又进行了第 二次的配置下发，则将两次的配置文件进行合并后再下发（如果配置项重复，则后一次会覆盖前 一次）。
前提条件
设备的产品模型中已定义该设备服务属性，且该属性支持可配置，在界面上传的配置 文件为JSON格式，才能完成配置更新下发。
单个设备配置更新
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤2 单击左下角 ，在“产品模型”界面上，单击设备所属产品模型的“详情”按 钮，“维护能力配置”中的“设备配置”设置为“支持”。
步骤3 进入“所有设备”页面，单击设备所在行的 按钮，可对设备进行配置更新。
步骤4 在弹出窗口中，按照下表配置参数。
参数名称 参数说明
任务名 创建设备配置下发的任务名称。
执行类型 任务的执行类型。分为“现在”、“设备在线时”、“自定义”。选 择“自定义”时需要设置“执行时间。”
执行时间 执行类型选择“自定义”时生效，设置任务执行的时间。
重试策略 ● 否：不重试。
● 自定义：需要设置重试次数。
重试次数 当“重试策略”为“自定义”时需要设置此参数。
重试间隔
（秒）
当“重试策略”为“自定义”时需要设置此参数。
配置文件 需要导入设备的配置文件，可点击下载上一次下发成功的配置文件信 息进行修改后再导入。
如果在此操作前，未对设备进行过配置下发的操作，点击下载设备配 置文件会提示“找不到资源”，这种情况下只能通过用户自定义的方 式，手动制作配置文件，支持配置下发修改的项需要与设备支持的能 力（设备对应的产品模型）保持一致，且配置文件需要为JSON格式，
例如：{ "sensitivity": "0", "dataReportInterval": "20"
}
----结束
批量设备配置更新
步骤1 登录物联网平台控制台，点击右上角“进入设备管理服务”。
步骤3 选择“ 批量任务> 批量设备配置”，单击页面右上角的“创建”。
步骤4 在弹出的“批量设备配置”窗口中，按照下表配置参数。
参数名称 参数说明 配置原则
任务名称 批量设备配置的任务名称。 按照实际情况填写。长度不超过 50的字符串。
是否使用策 略
批量设备配置执行策略是否需要配 置。
请根据实际情况选择，默认勾 选。
执行类型 选择批量设备配置的任务执行时
间。 ● 现在：任务创建完成后开
始。
● 设备在线时：当物联网平台 与设备互联时执行任务。
● 自定义：可以自定义选择开 始和结束时间。“开始时 间”和“结束时间”在“执 行类型”参数设置为“自定 义”时生效。
重试策略 任务失败后是否需要自动重新执
行，默认为“否”。 ● 否：不重新执行。
● 自定义：可自定义重试次 数。
重试次数 “重试策略”参数设置为“自定 义”时生效。
-
重试间隔
（秒）
“重试策略”参数设置为“自定 义”时生效。
-
步骤5 单击“下一步”，进入下一步配置。按照实际情况配置参数。
步骤6 选择需要批量配置下发的设备群组，单击“下一步”，跳转至文件上传页面。单击
，将整理好的Json格式设备配置信息文件上传。
配置文件制作方法：
● 之前有成功下发的配置文件：选择“设备 > 所有设备”，在右侧的窗口中单击相 同类型设备所在行的 按钮，在“配置文件”一栏，下载上一次下发成功的配置 文件文件进行修改后再导入。
● 之前未对设备进行过配置下发的操作：手动制作配置文件，支持配置下发修改的 项需要与产品模型里支持的能力保持一致，且配置文件需要为JSON格式，例如：
{ "sensitivity": "0", "dataReportInterval": "20"
}
步骤7 单击“提交”，完成批量设备配置任务创建。
步骤8 界面列表显示任务执行的状态和结果。如果成功率低于100%，则可以单击具体的任务 名称，进入任务详情，查看执行失败的原因。
----结束
相关 API 接口
查询设备服务能力
9 设备影子（联通用户专用）
非联通用户请查看设备接入服务。
概述
物联网平台支持创建设备的“影子”。设备影子是一个JSON文件，用于存储设备的在 线状态、设备最近一次上报的设备属性值、应用服务器期望下发的配置。每个设备有 且只有一个设备影子，设备可以获取和设置设备影子以此来同步设备属性值，这个同 步可以是影子同步给设备，也可以是设备同步给影子。
设备影子上有desired区和report区。
● desired区用于存储对设备属性的配置，即期望值。当需要修改设备的服务属性值 时，可修改设备影子的desired属性值，设备在线时，desired属性值立即同步到设 备。如果设备不在线，待设备上线或上报数据时，desired属性值同步到设备。
● report区用于存储设备最新上报的设备属性值，即上报值。当设备上报数据时，平 台刷新report属性值为设备上报的设备属性值。
说明
物联网平台仅支持对LWM2M协议的设备提供设备影子功能，对于希望通过设备影子修改的属 性，在定义Profile文件时，需遵循LWM2M协议中定义的属性，且属性类型为“W”。LWM2M 标准规范参见《OMA-TS-LightweightM2M-V1_0_2-20180209-A.pdf》。
应用场景
适合采用LWM2M协议的设备，特别是资源受限低功耗设备，长期处于休眠状态的场 景。
● 查询设备最新上报数据和设备最新在线状态：
– 当在控制台上查询设备上报数据时，由于设备可能长时间处于离线状态或因 网络不稳定掉线，而无法获取到最新数据。通过设备影子机制，设备影子中 始终保持设备最新上报的数据和设备当前状态，控制台上只需要查询设备影 子中存储的数据，即可获取设备最新上报的数据和设备状态。
– 很多应用服务器频繁的查询设备在线状态，由于设备处理能力有限，频繁查 询会损耗设备性能。使用设备影子机制，设备只需要主动同步状态给设备影 子一次，多个应用程序请求设备影子获取设备状态，即可获取设备最新状 态，从而将应用程序和设备解耦。
● 修改设备属性值：用户通过设备配置更新功能修改设备的属性值，由于设备可能 长时间处于离线状态，修改设备属性值的操作不能及时下发给设备。在这种情况 下，物联网平台可以将修改设备的属性信息存储在设备影子中，待设备上线后，
将修改的设备属性值同步给设备，从而完成设备属性值的修改。
业务流程
修改设备属性值
修改desired属性值，如果设备在线，则设备影子直接同步设备属性值到设备，否则等 待设备上线或上报数据时，再同步设备属性值到设备。
1. 用户通过控制台或应用服务器修改设备属性值。消息样例如下：
Method: PUT request:
https://server:port/iocm/app/shadow/v1.5.0/devices/devices/{deviceId}?appId={appId}
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json Body:
{ "serviceDesireds": [ {
"serviceId": "Temperature", "desired": {
"targetTemperature": 35 }
} ]}
2. 物联网平台修改desired属性值。
3. 物联网平台返回响应消息。
4. 物联网平台判断设备上线或上报数据。
5. 物联网平台将设备属性同步到设备。
6. 设备返回响应消息。
7. 当设备上报数据时，物联网平台修改report属性值为设备上报的设备属性值。
查询设备属性值
设备影子保存的是设备最新的设备属性值，一旦设备属性值产生变化，设备会将设备 属性值同步到设备影子。用户便可以及时获取查询结果，无需关注设备是否在线。
1. 用户通过控制台或应用服务器查询设备属性值。消息样例如下：
Method: GET request:
https://server:port/iocm/app/shadow/v1.5.0/devices/{deviceId}
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
2. 物联网平台返回desired属性值和report属性值，即期望值和上报值。消息样例如 下：response:
Status Code: 200 OK
Content-Type: application/json Body:
{ "deviceId": "******", "gatewayId": "******", "nodeType": "******", "createTime": "******", "lastModifiedTime": "******", "deviceInfo": "******""services": [ {
"serviceId": "******", "reportedProps": "******", "desiredProps": "******", "eventTime": "******", "serviceType": "******"
}, ]}
查询和修改设备影子
查询设备影子
方法1：应用服务器调用查询设备影子接口。
方法2：登录物联网平台控制台，点击右上角“进入设备管理服务”。单击左下角
，在设备列表中，单击具体的设备进入到设备的详情页面，在“设备影子”页 签中，可以查看当前设备属性数据，包括“上报值”和“期望值”，如下图所示。
● 如果当前界面中看到“上报值”与“期望值”不一致，原因可能是设备未在线，
暂时存储在设备影子中，待同步给设备，期望值会存在深色底纹。
● 如果当前界面看到的“上报值”与“期望值”一致，则表示设备最近一次上报的 属性值与用户期望下发的属性值一致，期望值为白色底纹。
修改设备影子
方法1：应用服务器调用修改设备影子接口。
