(高清版)GB∕T 38320-2019 信息技术 信息设备互连 智能家用电子系统终端设备与终端统一接入服务平台接口要求

L79中华人民共和国国家标准信息技术信息设备互连智能家用电子系统终端设备与终端统一接入服务平台接口要求I—Iv—Iv2019-12-10发布2020-07-01实施国家市场监督管理总局国家标准化管理委员会ⅠGB／T38320—2019前言 2规范性引用文件 3术语和定义 4缩略语 5接口通用消息参数定义 6无TLS网络传输环境下的消息参数定义 7TLS网络传输环境的消息参数定义 附录A（规范性附录）终端设备／应用客户端应答数据定义 ⅢGB／T38320—2019本标准按照GB/T1.1—2009给出的规则起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由全国信息技术标准化技术委员会(SAC/TC28)提出并归口。本标准起草单位：阿里巴巴（北京）软件服务有限公司、中国电子技术标准化研究院、小米科技有限责任公司、深圳赛西信息技术有限公司、上海庆科信息技术有限公司、京东方科技集团股份有限公司、松下家电研究开发（杭州）有限公司、杭州海康威视数字技术股份有限公司、青岛聚好联科技有限公司。本标准主要起草人：安勃、刘大鹏、杨宏、郭雄、周珏嘉、江小威、余晖、林峰、陈小松、刘涛、刘丽、1GB／T38320—2019信息技术信息设备互连智能家用电子系统终端设备与终端统一接入服务平台接口要求本标准规定了智能家用电子系统终端设备和网关设备与服务平台间接口通用消息参数定义、无TLS网络传输环境下的消息参数定义、TLS网络传输环境的消息参数定义。本标准适用于智能家用电子系统终端设备、网关设备和服务平台的设计、开发和部署。2规范性引用文件下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T37723—2019信息技术信息设备互连智能家用电子系统终端统一接入服务平台总体技术要求3术语和定义GB/T37723—2019界定的术语和定义适用于本文件。4缩略语下列缩略语适用于本文件。媒体访问控制(消息摘要算法第五版(设备序列号(传输层安全(国际协调时间(通用唯一标识符(5接口通用消息参数定义5.1无TLS网络传输环境下的接口通用消息参数定义无TLS网络传输环境下的接口通用消息参数定义见表1。2GB／T38320—2019表1无TLS网络传输环境下接口通用消息参数定义元素字段名称说明名称name根据使用的接口分别填写类型terminalInterface服务平台提供给终端的服务接口内容systemversion协议版本信息sign签名值key终端设备密钥的标识值timestanpUTC时间戳，自1970年1月1日起计算的时间，单位为requestdeviceID设备标识，终端设备的唯一标识，值为平台分配给终端设备的UUID,终端设备首次向平台注册时为空token终端统一接入服务平台颁发给设备的登录令牌chipID设备芯片标识target请求的数据对象account请求源使用的账号host请求操作源responseID（可选）响应控制类命令时，需将之前下发命令中携带的标识信息作为值parametersdeviceID设备标识attributeSet待更新的终端设备状态名称集合attributevalue终端设备状态值set:{}终端设备状态集合updateTime终端设备状态更新时间extension终端设备状态更新附加信息mac待注册终端设备的MAC信息。注册时与SN两者至少具备一个待注册终端设备的序列号。注册时与MAC两者至少具备一个model待注册终端设备的型号信息other待注册终端设备的附加信息请求返回值，取值见表A.1authToken服务平台颁发给用户的令牌service远程服务名account需要绑定的用户账号errorCode远程服务执行后的错误代码，用户自定义arguments远程服务所需要的参数，若不需要参数，则取值为即可3GB／T38320—2019元素字段名称说明内容parametersresultset:{}远程服务返回值，按服务自行定义结构updateTime终端设备状态值更新时间extension终端设备状态更新附加信息client:{}连接的子设备的设备标识列表，填写平台分配给子设备的UUIDversion固件版本号resourceUrl固件的统一资源定位标志md5固件文件MD5固件文件大小zip是否压缩step固件升级步骤stepPercent固件升级进度百分比dataID数据标识注代表包含数组。5.2TLS网络传输环境下的接口通用消息参数定义TLS网络传输环境下的接口通用消息参数定义见表2。表2TLS网络传输环境下接口通用消息参数定义元素字段名称说明名称name根据使用的接口分别填写类型terminalInterface面向终端的接口内容deviceID服务平台分配的设备标识，设备生产时预置device_random终端设备生成的随机字符串设备支持的签名算法cert服务平台签发的设备证书请求返回值，取值见表A.2message代码的补充消息cloud_random服务平台生成的随机字符串sign哈希值serverTime服务平台系统时间parametersserviceInstanceID服务实例标识propertyInstanceID属性实例标识value属性值4GB／T38320—2019元素字段名称说明内容parameterseventInstanceID事件实例标识actionInstanceID方法实例标识argumentsserviceInstanceID服务实例标识propertyInstanceID属性实例标识value属性值请求返回值，取值见表A.26无TLS网络传输环境下的消息参数定义基础功能，用于请求登录终端设备，登录成功后可建立与服务平台的业务通道。终端设备登录请求消息参数定义见表3。表3登录请求消息参数定义元素字段名称必选说明名称loginDevice是终端设备登录类型terminalInterface是服务平台提供给终端的服务接口内容systemversion是协议版本sign是签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备标识token是设备令牌chipID是终端设备芯片标识target是对象，此处为空responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值parameters是 loginDeviceDataID是数据标识5GB／T38320—20196.2终端设备获取服务平台的系统时间基础功能，用于请求获取服务平台的系统时间。终端设备获取服务平台系统时间的请求消息参数定义见表4。表4获取服务平台系统时间请求消息参数定义元素字段名称必选说明名称getTime是获取服务平台系统时间类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备标识chipID是终端设备芯片标识target是请求的数据对象，此处为空parameters是 getTimeDataID是数据标识6.3终端设备状态控制命令基础功能，用于请求服务平台来控制远程终端设备。终端设备的状态控制命令请求消息参数定义见表5。表5状态控制命令请求消息参数定义元素字段名称必选说明名称setDeviceStatus是终端设备收到的设置操作类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳6GB／T38320—2019元素字段名称必选说明内容requestaccount是请求源使用的账号host是请求操作源parametersdeviceID是设备标识attributeSet否待更新的终端设备状态名称集合attributevalue否终端设备状态值set:{}否终端设备状态集合extension否终端设备状态更新附加信息setDeviceStatusDataID是数据标识终端设备的批量状态控制命令请求消息参数定义见表6。表6批量状态控制命令请求消息参数定义元素字段名称必选说明名称是终端设备收到的设置操作类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestaccount是请求源使用的账号标识host是请求操作源parametersdeviceID是设备标识attributeSet否待更新的终端设备状态名称集合attributevalue否终端设备状态值set:{}否终端设备状态集合extension否终端设备状态更新附加信息是消息标识6.4终端设备状态查询命令基础功能，用于请求服务平台来查询远程终端设备状态。终端设备的状态查询命令请求消息参数定义见表7。7GB／T38320—2019表7状态查询命令请求消息参数定义元素字段名称必选说明名称getDeviceStatus是终端设备收到的查询操作类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestaccount是请求源使用的账号标识host是请求操作源parametersdeviceID是设备标识attributeSet否待更新的终端设备状态名称集合getDeviceStatusDataID是消息标识6.5终端设备数据上报基础功能，用于终端设备上传数据、保持心跳。终端设备的数据上报请求消息参数定义见表8。表8数据上报请求消息参数定义元素字段名称必选说明名称postDeviceData是终端设备上报数据类型是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备标识chipID是终端设备芯片标识target是请求数据的发送对象。自主上报时置为空；响应控制命令时，需将命令中携带的应信息作为值responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值8GB／T38320—2019元素字段名称必选说明内容parametersattributeSet否终端设备上传状态名称集合（方便接收端解析用）attributevalue否终端设备状态值set:{}否终端设备状态集合updateTime否终端设备状态更新时间extension否终端设备状态更新附加信息postDeviceDataDataID是消息标识终端设备的数据批量上报请求消息参数定义见表9。表9数据批量上报请求消息参数定义元素字段名称必选说明名称是终端设备上报数据集类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备标识chipID是终端设备芯片标识target是请求数据的发送对象。自主上报时置为空；响应控制命令时，需将命令中携带的应信息作为值responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值parametersattributeSet否终端设备上传状态名称集合（方便接收端解析用）attributevalue否终端设备状态值set:{}否终端设备状态集合updateTime否终端设备状态更新时间extension否终端设备状态更新附加信息是消息标识6.6终端设备远程服务调用请求基础功能，用于请求服务平台进行远程调用终端设备提供的服务。9GB／T38320—2019终端设备接收的远程服务调用请求消息参数定义见表10。表10远程服务调用请求消息参数定义元素字段名称必选说明名称requestRemoteService是终端设备收到的调用操作类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestaccount是请求源使用的账号标识host是请求操作源parametersdeviceID是设备标识service是远程服务名arguments是远程服务所需要的参数，若不需要参数，则取值为即可requestRemoteServiceDataID是消息标识6.7终端设备上报远程服务的响应结果基础功能，用于向服务平台反馈远程服务调用结果。终端设备的远程服务响应结果上报请求消息参数定义见表11。表11远程服务响应结果上报请求消息参数定义元素字段名称必选说明名称postRemoteServiceResponse是终端设备上报远程服务响应结果类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备标识chipID是终端设备芯片标识target是请求数据的发送对象需将之前命令中携带的信息作为值responseID否需将之前下发的命令中携带的标识信息作为值GB／T38320—2019元素字段名称必选说明内容parametersdeviceID是注册此服务的终端设备标识。如果响应子设备远程服务结果，则填写子设备标识service否中调用的服务名称errorCode是远程服务执行后的错误编码，用户自定义resultset:{}否远程服务返回值，按服务自行定义结构updateTime否终端设备状态值更新时间extension否终端设备状态更新附加信息postRemoteServiceResponseDataID是消息标识6.8终端设备远程服务的注册与注销扩展功能，用于向服务平台注册和注销终端设备可对外提供的服务接口，应用客户端或第三方智能家用电子系统终端设备可通过服务平台启用此终端设备已注册的远程服务。终端设备的远程服务注册请求消息参数定义见表12。表12远程服务注册请求消息参数定义元素字段名称必选说明名称registerRemoteService是终端设备注册服务接口类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是终端设备芯片标识parametersdeviceID是终端设备标识。注册此服务的终端设备标识。如果注册子设备远程服务结果，则填写子设备标识service是终端设备可以对外提供的服务接口registerRemoteServiceDataID是消息标识终端设备的远程服务注销请求消息参数定义见表13。GB／T38320—2019表13远程服务注销请求消息参数定义元素字段名称必选说明名称unregisterRemoteService是终端设备注销服务接口类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是终端设备芯片标识parametersdeviceID是终端设备标识。注销此服务的终端设备标识。如果注销子设备远程服务结果，则填写子设备标识service是终端设备注销的服务接口unregisterRemoteServiceDataID是消息标识6.9终端设备绑定用户请求扩展功能，用于终端设备请求与当前用户进行绑定。终端设备的绑定用户请求消息参数定义见表14。表14绑定用户请求消息参数定义元素字段名称必选说明名称bindUserByDevice是终端设备绑定用户请求类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是终端设备芯片标识target是请求数据的发送对象，此处为空responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值parametersaccount是需要绑定的用户账号bindUserByDeviceDataID是消息标识GB／T38320—20196.10终端设备升级固件请求扩展功能，用于终端设备的固件升级。终端设备接收的升级固件请求消息参数定义见表15。表15终端设备升级固件请求消息参数定义元素字段名称必选说明名称upgradeDevice是升级终端设备固件版本类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestaccount是请求源使用的账号标识host是请求操作源parametersdeviceID是设置对象终端设备的设备标识信息version是固件版本号resourceUrl是固件的统一资源定位标志md5是固件文件MD5是固件文件大小zip是是否压缩upgradeDeviceDataID是消息标识6.11终端设备取消升级固件请求扩展功能，用于取消终端设备的固件升级。终端设备接收的取消升级固件请求消息参数定义见表16。表16终端设备取消升级固件请求消息参数定义元素字段名称必选说明名称unUpgradeDevice是取消升级终端设备固件版本类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳GB／T38320—2019元素字段名称必选说明内容requestaccount是请求源使用的账号标识host是请求操作源parametersdeviceID是设置对象终端设备的设备标识信息unUpgradeDeviceDataID是消息标识6.12终端设备上报固件升级状态扩展功能，用于终端设备向服务平台上报固件升级状态。终端设备的固件升级状态上报请求消息参数定义见表17。表17终端设备固件升级状态上报请求消息参数定义元素字段名称必选说明名称postDeviceUpgradeStatus是上报终端设备固件升级的状态类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是终端设备芯片标识target否请求数据的发送对象需将之前命令中携带的信息作为值responseID是响应控制命令时，需将之前下发命令中携带的标识信息作为值parametersstep是升级步骤“0”为初始状态，表示未开始升级；“1”代表固件开始下载；“2”代表固件开始解压；“3”代表固件开始验证；“4”代表固件开始刷“5”代表固系统重启；“6”代表升级成功重启成功；代表初始化失败；代表下载失败；代表解压失败；代表校验失败；代表烧写失败；GB／T38320—2019元素字段名称必选说明内容parametersstep是代表重启失败；代表升级失败重启stepPercent否升级各阶段的进度百分比version是正在升级的固件版本号postDeviceUpgradeStatusDataID是消息标识6.13网关设备注册子设备扩展功能，用于网关设备为与其连接的子设备向服务平台进行注册。网关设备注册子设备请求消息参数定义见表18。表18网关设备注册子设备请求消息参数定义元素字段名称必选说明名称registerSubDevice是向服务平台注册一个子设备，服务平台会根据子设备的一些表示唯一性的强制属性来给子设备生成一个UUID类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是网关设备芯片标识target是请求的数据对象，此处为空parametersmac否待注册子设备的MAC信息。注册时与SN两者至少具备一个否待注册子设备的序列号。注册时与MAC两者至少具备一个model是待注册子设备的型号信息other否待注册子设备的其他信息registerSubDeviceDataID是消息标识GB／T38320—20196.14网关设备上报子设备连接、断连状态扩展功能，用于网关设备向服务平台上报子设备连接、断连状态。网关设备上报子设备连接状态的请求消息参数定义见表19。表19网关设备上报子设备连接状态请求消息参数定义元素字段名称必选说明名称attachSubDevice是子设备连接状态更新类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是网关设备芯片标识target是请求的数据发送对象，此处为空responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值parametersdeviceID是网关设备的设备标识client:{}是连接的子设备的设备标识列表，填写服务平台分配给子设备的UUIDattachSubDeviceDataID是消息标识网关设备上报子设备断连状态的请求消息参数定义见表20。表20网关设备上报子设备断连状态请求消息参数定义元素字段名称必选说明名称detachSubDevice是子设备断连状态更新类型terminalInterface是服务平台提供的终端设备服务接口内容systemversion是协议版本sign否签名值key是终端设备密钥的标识值timestamp是时间戳requestdeviceID是设备的标识chipID是网关设备芯片标识target是请求数据的发送对象，此处为空responseID否响应控制命令时，需将之前下发命令中携带的标识信息作为值GB／T38320—2019元素字段名称必选说明内容parametersdeviceID是网关设备的设备标识client:{}是断连的子设备的设备标识列表，填写平台分配给子设备的UUIDdetachSubDeviceDataID是消息标识7TLS网络传输环境的消息参数定义基础功能，用于请求登录终端设备，登录成功后可建立与服务平台的业务通道。登录请求消息参数定义见表21。表21登录请求消息参数定义元素字段名称必选说明名称loginDevice是终端设备登录类型terminalInterface是服务平台提供给终端的服务接口内容deviceID是服务平台分配的设备标识，设备生产时预置device_random是终端设备生成的随机字符串是设备支持的签名算法1:HMAC-SHA256(PSK)2:ECDSA-SHA256基于哈希的消息验证码；椭圆曲线数字签名算法）cert否服务平台签发的设备证书，使用ECDSA签名时，该字段必选登录响应消息参数定义见表22。表22登录响应消息参数定义元素字段名称必选说明名称loginDeviceResponse是终端设备登录响应类型terminalInterface是服务平台提供给终端的服务接口内容是登录结果，代码取值见表A.2message否代码的补充消息cloud_random否服务平台生成的随机字符串否服务平台选定的签名算法GB／T38320—2019附加认证响应消息参数定义见表23。表23附加认证响应消息参数定义元素字段名称必选说明名称是终端设备登录响应类型terminalInterface是服务平台提供给终端的服务接口类型deviceID是服务平台分配的设备标识，设备生产时预置sign是哈希签名值7.2终端设备获取服务平台的系统时间基础功能，用于此接口用于请求获取服务平台的系统时间。获取时间请求消息参数定义见表24。表24获取时间请求消息参数定义元素字段名称必选说明名称getTime是获取服务平台系统时间类型terminalInterface是服务平台提供的终端设备服务接口内容deviceTime是8个八位位组时间戳信息serverTime是取值为0获取时间响应消息参数定义见表25。表25获取时间响应消息参数定义元素字段名称必选说明名称getTimeResponse是获取服务平台系统时间的响应类型terminalInterface是服务平台提供的终端设备服务接口内容deviceTime是8个八位位组时间戳信息ServerTime是8个八位位组时间戳信息7.3终端设备状态查询命令基础功能，用于请求服务平台来查询远程终端设备状态。终端设备状态查询请求消息参数定义见表26。GB／T38320—2019表26终端设备状态查询请求消息参数定义元素字段名称必选说明名称getDeviceStatus是终端设备收到的查询操作类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识method是取值为“读属性”parametersdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识终端设备状态查询响应消息参数定义见表27。表27终端设备状态查询响应消息参数定义元素字段名称必选说明名称getDeviceStatusResponse是终端设备查询操作的响应类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识，与终端设备状态查询请求消息里的标识一致parametersdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识value条件必选时存在是代码取值见表A.27.4终端设备状态控制命令基础功能，用于请求服务平台来控制远程终端设备。终端设备状态控制请求消息参数定义见表28。表28终端设备状态控制请求消息参数定义元素字段名称必选说明名称setDeviceStatus是终端设备收到的设置操作类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识method是取值为“写属性”parametersdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识value是属性值GB／T38320—2019终端设备状态控制响应消息参数定义见表29。表29终端设备状态控制响应消息参数定义元素字段名称必选说明名称setDeviceStatusResponse是终端设备控制操作的响应类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识，与终端设备状态控制查询请求消息里的标识一致parametersdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识是代码取值见表A.27.5终端设备数据上报基础功能，用于终端设备向服务平台上报数据。属性上报请求消息参数定义见表30。表30属性上报请求消息参数定义元素字段名称必选说明名称postDeviceData是终端设备上报数据类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识method是取值为“属性上报”parametersdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识value是属性值7.6终端设备远程服务调用请求基础功能，用于请求服务平台来远程调用终端设备提供的服务。GB／T38320—2019远程服务调用请求消息参数定义见表31。表31远程服务调用请求消息参数定义元素字段名称必选说明名称requestRemoteService是终端设备收到的调用操作类型terminalInterface是服务平台提供的终端设备服务接口内容ID是请求标识method是取值为“执行方法”parametersactionInstanceID是方法实例标识argumentsdeviceID是设备标识serviceInstanceID是服务实例标识propertyInstanceID是属性实例标识value是属性值远程服务调用响应消息参数定义见表32。表32远程服务调用响应消息参数定义元素字段名称必选说明名称requestRemoteServiceResponse是调用操作的响应类型terminalInterfac