DB23_T 3080-2022 黑龙江工业互联网标识解析（综合型）二级节点公共服务平台数据接口规范.docx
ICS 35.240.99CCS L 6723黑龙江省地方标准DB 23/T 30802022黑龙江工业互联网标识解析（综合型）二级节点公共服务平台数据接口规范2022 - 01 - 29 发布2022 - 03 - 01 实施黑龙江省市场监督管理局发 布DB23/T 30802022目次前言. II1 范围. 12 规范性引用文件.13 术语和定义.14 缩略语.25 总体框架与基本要求.25.1 总体框架.25.2 二级节点技术要求.25.3 二级节点接口要求.35.4 企业节点标识注册要求.36 标识注册.36.1 基于 Handle 数据类型创建标识.36.2 基于数据模板创建标识.87 标识查询.127.1 必须带前缀的查询.127.2 可以省略前缀的查询.13附录 A （资料性） 状态码.15参考文献. 16IDB23/T 30802022前言本文件按照GB/T 1.12020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由黑龙江省工业和信息化厅提出、归口并组织实施。本文件由黑龙江省工业信息化发展中心（黑龙江省电子技术研究所）解释。本文件起草单位：黑龙江省工业信息化发展中心（黑龙江省电子技术研究所）、黑龙江省标准化研究院、黑龙江然也科技有限公司、黑龙江省创新推广工业互联网发展中心有限公司。本文件主要起草人：郑显生、董力、朱颖滨、王淼庚、施晓林、刘澍、陈要武、郭宇亮、袁良武、车涵、李辉、张敬、周文华、姜欣、赵金晓、李宝才、张智、王军、刘鹏林。本文件为首次发布。IIDB23/T 30802022黑龙 江工业 互联网 标识解 析（综 合型） 二级节 点公共 服务平 台数据接口规范1 范围本文件规定了黑龙江工业互联网标识解析（综合型）二级节点公共服务平台的总体框架与基本要求，以及标识注册、标识查询等数据接口要求。本文件适用于黑龙江省工业互联网标识解析（综合型）二级节点与企业节点间的数据接口管理。2 规范性引用文件本文件没有规范性引用文件。3 术语和定义下列术语和定义适用于本文件。3.1标识编码能够唯一识别机器、产品等物理资源和算法、工序等虚拟资源的身份符号。3.2标识注册针对工业互联网标识编码的规划、申请与分配、使用情况反馈、生命周期管理、标识有效性管理，标识分配使用情况的信息收集以及标识关联信息的采集等功能。3.3标识解析根据标识编码查询目标对象网络位置或者相关信息。3.4国家顶级节点国家或地区内部最顶级的标识服务节点，能够面向全国范围提供顶级标识解析服务，以及标识备案、标识认证等管理能力。3.5标识解析二级节点1DB23/T 30802022面向特定行业或者多个行业提供标识服务的公共节点，以下简称为二级节点。3.6企业节点企业内部的标识服务节点，能够面向特定企业提供标识注册、标识解析服务、标识数据服务等，既可以独立部署，也可以作为企业信息系统的组成要素。4 缩略语下列缩略语适用于本文件。API：应用程序接口（Application Programming Interface)HDFS：Hadoop分布式文件系统（Hadoop Distributed File System）HBASE：Hadoop数据库（Hadoop Database）RDBMS：关系式数据库管理系统（Relational Database Management System）5 总体框架与基本要求5.1 总体框架黑龙江省工业互联网标识解析（综合型）二级节点公共服务平台的总体框架示意图，见图1。图1 公共服务平台接口框架示意图5.2 二级节点技术要求2参数类型参数名字段长度参数说明备注StringappId30为每家企业分配的 APPID ，接口调试前需要向相应人员索取。必填StringhandleDataType50Handle 数据类型，即标识注册时相应字段的名称。必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 30802022应满足下列条件：a)服务可用性应达到 99.99%以上；b)支持 IPv4 、IPv6 双协议栈的标识注册及解析服务；c)支持对企业节点及标识查询客户端的双向身份认证；d)支持对标识解析过程中数据传输的机密性与完整性保护；e)支持对标识信息的访问权限控制能力；f)具备流量重定向等拒绝服务攻击防护能力。5.3 二级节点接口要求应满足下列条件：a)提供标识注册 、标识解析等相关接口；b)采用 UTF-8 字符编码, Content-Type 为 application/json；c)除特殊指定外 ，接口请求方式为 POST；d)提供基于 Handle 数据类型创建标识的接口和基于数据模板创建标识的接口。5.4 企业节点标识注册要求在中华人民共和国境内依法登记注册具有独立法人资格的企业、事业单位、社会团体。6 标识注册6.1 基于 Handle 数据类型创建标识6.1.1 创建 Handle 数据类型6.1.1.1 请求路径：/api/loongxy-lxhl/lxhl/createHandleDataType。6.1.1.2 请求方式：POST。6.1.1.3 请求参数，见表 1。表1 基于 Handle 数据类型创建标识的请求参数6.1.1.4 响应参数，见表 2。表2 基于 Handle 数据类型创建标识的响应参数3参数类型参数名字段长度参数说明备注StringappId30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填Arrayitems标识属性列表必填Intitemsi.index8标识属性索引，不填则默认从 10000 开始。非必填Stringitemsi.handleDataType505.1.1 接口创建的 Handle 数据类型必填Stringitemsi.value2000标识属性内容值非必填Arrayitemsi.references标识引用列表非必填Stringitemsi.referencesj.handle200引用的标识码，如果与 handle 字段工业互联网前缀一致， 则可以省略工业互联网前缀。如果引用的是其他企业的码，则必须加上工业互联网前缀。非必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 308020226.1.1.5 测试用例，格式如下。示例："appId" : "企业唯一appId","handleDataType" : "SIZE"6.1.2 根据 Handle 数据类型创建标识6.1.2.1 请求路径：/api/loongxy-lxhl/lxhl/createHandleByType 。6.1.2.2 请求方式：POST。6.1.2.3 请求参数，见表 3。表3 根据 Handle 数据类型创建标识6.1.2.4 响应参数，见表 4。表4 根据 Handle 数据类型创建标识的响应参数6.1.2.5 测试用例，格式如下。示例："appId":"企业唯一 appId", "handle":"2000091","items": 4参数类型参数名字段长度参数说明备注StringappId30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填Arrayitems标识属性列表必填Intitemsi.index8标识属性索引，不填则默认从 10000 开始非必填Stringitemsi.handleDataType505.1.1 接口创建的 Handle 数据类型必填Stringitemsi.value2000标识属性内容值非必填Arrayitemsi.references标识引用列表非必填DB23/T 30802022"handleDataType":"PRODUCT_NAME", "value": "菠萝","handleDataType":"PRICE", "value": "8.5","handleDataType":"BATCHNO", "references": "handle": "88.210.366669/2000079","handle": "2000090"6.1.3 根据 Handle 数据类型添加标识项6.1.3.1 请求路径：/api/loongxy-lxhl/lxhl/addHandleItemByType 。6.1.3.2 请求方式：POST。6.1.3.3 请求参数，见表 5。表5 根据 Handle 数据类型添加标识项5参数类型参数名字段长度参数说明备注Stringitemsi.referencesj.handle200引用的标识码，如果与 handle 字段工业互联网前缀一致， 则可以省略工业互联网前缀。如果引用的是其他企业的码，则必须加上工业互联网前缀。非必填参数类型参数名字段长度参数说明备注StringappId30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填Arrayitems标识属性列表必填DB23/T 30802022表5 根据 Handle 数据类型添加标识项（续）6.1.3.4 响应参数，见表 6。表6 根据 Handle 数据类型添加标识项的响应参数参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象6.1.3.5 测试用例，格式如下。示例："appId": "企业唯一 appId", "handle":"2000094","items": "handleDataType":"BATCHNO", "value": "A0310001"6.1.4 根据 Handle 数据类型修改标识值6.1.4.1 请求路径：/api/loongxy-lxhl/lxhl/updateHandleByType 。6.1.4.2 请求方式：POST。6.1.4.3 请求参数，见表 7。表7 根据 Handle 数据类型修改标识值6参数类型参数名字段长度参数说明备注Intitemsi.index8标识属性索引，必须与注册时标识属性索引一致必填Stringitemsi.handleDataType505.1.1 接口创建的 Handle 数据类型必填Stringitemsi.value2000标识属性内容值非必填Arrayitemsi.references标识引用列表非必填Stringitemsi.referencesj.handle200引用的标识码，如果与 handle 字段工业互联网前缀一致， 则可以省略工业互联网前缀。如果引用的是其他企业的码，则必须加上工业互联网前缀。非必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 30802022表7 根据 Handle 数据类型修改标识值（续）6.1.4.4 响应参数，见表 8。表8 根据 Handle 数据类型修改标识值的响应参数6.1.4.5 测试用例，格式如下。示例："appId": "企业唯一 appId", "handle":"2000094","items": "index": 10000,"handleDataType":"PRODUCT_NAME", "value": "西瓜","index":10001,"handleDataType":"PRICE","value": "5.0"7参数类型参数名字段长度参数说明备注StringappId30必填StringtemplateName50模板名称。如果存在则修改模板，否则新增模板。必填Stringdescription500模板描述非必填Arrayitems模板项列表必填Stringitemsi.nameCn50字段中文名必填Stringitemsi.nameEn50字段英文名必填Booleanitemsi.required10是否必填必填Intitemsi.minLength10字段最小长度必填Intitemsi.maxLength10字段最大长度必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 308020226.2 基于数据模板创建标识6.2.1 创建或修改数据模板6.2.1.1 请求路径：/api/loongxy-lxhl/lxhl/saveTemplate。6.2.1.2 请求方式：POST。6.2.1.3 请求参数，见表 9。表9 创建或修改数据模板6.2.1.4 响应参数，见表 10。表 10 创建或修改数据模板的响应参数6.2.1.5 测试用例，格式如下。示例："appId": "企业唯一 appId", "templateName":"neil-0310","description": "Neil测试模板","items": "nameCn": "名称","nameEn":"name", "required":true,"minLength": 2,"maxLength": 208参数类型参数名字段长度参数说明备注StringappId30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填StringtemplateName50模板名称必填Arrayitems标识属性列表必填intitemsi.index8标识属性索引（不能为 1001）必填Stringitemsi.name50标识属性类型,对应数据模板的 nameEn。必填Stringitemsi.value2000标识属性内容值必填DB23/T 30802022,"nameCn": "颜色","nameEn":"color","required":true,"minLength": 1,"maxLength": 10,"nameCn": "价格","nameEn":"price", "required":false,"minLength": 1,"maxLength": 106.2.2 根据模板创建标识6.2.2.1 请求路径：/api/loongxy-lxhl/lxhl/createHandleByTemplate 。6.2.2.2 请求方式：POST。6.2.2.3 请求参数，见表 11。表 11 根据模板创建标识6.2.2.4 响应参数，见表 12。9参数类型参数名字段长度参数说明备注StringappId30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 30802022表 12 根据模板创建标识的响应参数6.2.2.5 测试用例，格式如下。示例："appId": "企业唯一 appId","templateName":"neil-0310", "handle": "2000097","items": "index":2000, "name": "name","value": "APPLE","index": 2001, "name": "color","value": "红色","index": 2002, "name": "price","value": "5999"6.2.3 根据模板修改标识6.2.3.1 请求路径：/api/loongxy-lxhl/lxhl/updateHandleByTemplate 。6.2.3.2 请求方式：POST。6.2.3.3 请求参数，见表 13。表 13 根据模板修改标识10参数类型参数名字段长度参数说明备注StringtemplateName50模板名称必填Arrayitems标识属性列表必填intitemsi.index8标识属性索引,索引值必须与注册时对应属性的索引值一致。必填Stringitemsi.name50标识属性类型,对应数据模板的 nameEn。必填Stringitemsi.value2000标识属性内容值必填参数类型参数名备注Integercode状态码(详见附录 1)Stringmsg提示信息Objectobj返回的对象DB23/T 30802022表 13 根据模板修改标识（续）6.2.3.4 响应参数，见表 14。表 14 根据模板修改标识的响应参数6.2.3.5 测试用例，格式如下。示例："appId": "企业唯appId", "templateName":"neil-0310","handle": "2000097","items": "index": 2000,"name": "name","value": "猕猴桃","index": 2001,"name": "color","value": "yellow",11参数类型参数名参数说明备注IntresponseCode响应码Stringhandle查询的标识Stringmsg提示信息Arrayitems标识属性列表Intitemsi . index标识属性索引Stringitemsi . name标识属性类型Stringitemsi .value标识属性内容值Stringitemsi .timestamp时间戳参数类型参数名字段长度参数说明备注String标识码200必须加上工业互联网前缀必填DB23/T 30802022"index": 2002,"name": "price","value": "8.9"7 标识查询7.1 必须带前缀的查询7.1.1 请求路径：/api/loongxy-lxhl/lxhl/queryHandle?handle=标识码。7.1.2 请求方式：GET。7.1.3 请求参数，见表 15。表 15 必须带前缀查询的请求参数7.1.4 响应参数，见表 16。表 16 必须带前缀查询的响应参数7.1.5 测试用例，格式如下。示例："responseCode" : 1,"handle" : "88.210.366669/2000097","msg" : "","items" : "index" : 2000,12参数类型参数名参数说明备注IntresponseCode响应码Stringhandle查询的标识Stringmsg提示信息Arrayitems标识属性列表Intitemsi.index标识属性索引Stringitemsi.name标识属性类型参数类型参数名字段长度参数说明备注Stringappid30必填Stringhandle200标识码。可以加上工业互联网前缀也可以不加前缀。必填DB23/T 30802022"name" : "name","value": "猕猴桃","timestamp" : "2021-03-10 12:08:06","index" : 2001,"name" : "color","value" : "yellow","timestamp" : "2021-03-10 12:08:06","index" : 2002,"name" : "price","value" : "8.9","timestamp" : "2021-03-10 12:08:06"7.2 可以省略前缀的查询7.2.1 请求路径：/api/loongxy-lxhl/lxhl/queryHandle。7.2.2 请求方式：POST。7.2.3 请求参数，见表 17。表 17 可以省略前缀的查询7.2.4 响应参数，见表 18。表 18 可以省略前缀的查询的响应参数13参数类型参数名参数说明备注Stringitemsi.value标识属性内容值Stringitemsi.timestamp时间戳DB23/T 30802022表 18 可以省略前缀的查询的响应参数（续）7.2.5 测试用例，格式如下。示例："appId":"企业唯一 appId","handle": "2000097"或"appId": "企业唯一 appId","handle": "88.210.366669/2000097"14状态码提示信息1成功-1操作失败1001APPID 不能为空1002APPID 不正确1003企业尚未通过公共服务平台分配1004企业尚未通过国家顶级节点审核1005标识码不能为空1006没有操作该前缀的权限1007标识项不能为空1008模板名称不能为空1009模板项不能为空1010用户不存在1011获取 Token 失败1012模板名称已存在1013模板名称不能为空1014模板不存在DB23/T 30802022AA附 录 A（资料性）状态码A.1 状态码对应的提示信息，见表A.1。表 A.1 状态码说明15DB23/T 30802022参考文献1 GB/T 39443-2020 公共信用信息交换方式及接口规范2 GB/T 40094.3-2021 电子商务数据交易 第 3 部分：数据接口规范3 YD/T 3844-2021 工业互联网平台 应用管理接口要求_16
