DB32_T 3410-2018 食品安全电子追溯数据目录服务数据接口规范.pdf

ICS 67.040 X 00 备案号：60246-2018 DB32 江苏省地方标准 DB 32/T 34102018 食品安全电子追溯数据目录服务数据 接口规范 Interface specifications of data catalog service for food safety electronic traceability 2018-6-25 发布 2018-7-10 实施 江苏省质量技术监督局 发 布 目 次 前言.III 1 范围.1 2 规范性引用文件.1 3 术语和定义.1 4 缩略语.2 5 功能要求.2 5.1 网元交互.2 5.2 基本服务功能.3 6 数据接口.3 6.1 基本要求.3 6.2 接口原语.4 6.3 数据类型.4 6.4 调用方式.5 6.5 参数要求.5 6.5.1 DCS 标识注册接口.5 6.5.2 DCS 标识更新接口.6 6.5.3 DCS 标识删除接口.6 6.5.4 DCS 主数据登记接口.7 6.5.5 DCS 事件登记接口.8 6.5.6 DCS 追溯信息查询接口.8 附录 A（规范性附录）Item 类型参数.10 附录 B（资料性附录）数据接口应用示例.11 前 言 本标准按照GB/T 1.1-2009给出的规则起草。本标准由江苏省食品药品监督管理局提出并归口。本标准起草单位：江苏省质量和标准化研究院、江苏省食品药品监督信息中心、中科院计算机网络中心、复旦大学无锡研究院、江苏瑞德信息产业有限公司、无锡捷玛物联科技有限公司。本标准主要起草人：杨博、刘佳、吴双力、田野、胡冶、曹云、刘毅、周广军、王理、王俊宇、钱侃、刘小康。食品安全电子追溯数据目录服务数据接口规范 1 范围 本标准规定了食品安全电子追溯数据目录服务的功能要求、数据接口。本标准适用于食品安全电子追溯数据目录服务的接口实现。2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB 12904 商品条码 零售商品编码与条码表示 DB32/T XXXX-2018 食品安全电子追溯标识解析服务数据接口规范 RFC 2616 超文本传输协议1.1(Hypertext transfer protocol-HTTP/1.1)RFC 4627 JSON格式定义(The application/JSON media type for javascript object notation)RFC 4825 可扩展标记语言配置接入协议(The extensible markup language(XML)configuration access protocol(XCAP)3 术语和定义 下列术语和定义适用于本文件。3.1 数据目录服务 data catalog service 以物品的追溯标识为索引建立物品所流经的信息查询服务器URL地址列表的过程。3.2 网元 network element 由软硬件共同组成的能实现网络中的一种或多种逻辑功能的逻辑单元。3.3 IRS网元 identification resolution service network element 提供追溯标识注册和追溯标识解析服务的网元。3.4 IQS网元 information query service network element 提供可视化追溯信息查询服务的网元。3.5 DCS网元 data catalog service network element 以追溯标识为单位提供追溯路径的建立和查询服务的网元。3.6 追溯代理 traceability proxy 以用户发起的HTTP追溯查询请求为触发，代替追溯用户调用IRS,DCS和IQS网元的多个接口完成追溯查询逻辑功能的网元。3.7 EU网元 end user network element 终端用户所使用的具备追溯查询能力的软件系统的统称。3.8 CU网元 capture unit network element 负责采集主数据、交易数据和事件数据并提交到IQS网元，完成数据采集功能的网元。3.9 SP网元 supervisor platform network element 接收IQS网元上报的追溯数据，支撑政府监管人员利用追溯数据开展对企业监管的网元。4 缩略语 下列缩略语适用于本文件。CU：捕获单元(Capture Unit)DNS：域名服务(Domain Name Service)DCS：数据目录服务(Data Catalog Service)EU：终端用户(End User)GTIN：全球贸易项目代码(Global Trade Item Number)IQS：信息查询服务(Information Query Service)IRS：标识解析服务(Identification Resolution Service)JSON：JS对象标记(Java Script Object Notation)RFID：射频识别(Radio Frequency Identification)SP：监管平台(Supervisor Platform)URL：统一资源定位符(Uniform Resource Locator)URN：统一资源名称(Uniform Resource Name)XML：可扩展标记语言(Extensible Markup Language)5 功能要求 5.1 网元交互 5.1.1 总则 食品安全电子追溯系统应由企业平台、监管平台和查询平台组成。食品安全电子追溯系统的系统架构见DB32/T XXXX。DCS网元应按归属地管理的原则进行业务管理，部署在归属地生产企业的IQS网元应向负责管理归属地业务的DCS网元发起标识注册和事件登记。DCS网元应将本地区IQS网元注册的物品追溯标识同步向IRS网元发起注册。DCS网元归属地管理架构图见图1。EU网元追溯代理IRS网元DCS网元(归属地)IRS标识管理接口IRS解析查询接口Web/APP/微信服务查询平台DCS查询接口DCS网元IRS标识管理接口IQS网元(生产企业)DCS标识管理接口DCS事件登记接口 图1 DCS 网元归属地管理架构图 5.1.2 网元要求 5.1.2.1 IRS网元应对外提供追溯标识注册和追溯标识解析服务。5.1.2.2 DCS网元应以追溯标识为单位提供追溯路径的建立和查询的服务。DCS网元应以追溯标识为标识确保物品的可追溯性。5.1.2.3 IQS网元应提供追溯信息捕获、查询服务和数据上报服务的功能。5.1.2.4 CU网元应通过条码识读设备和RFID读写器等数据采集设备采集一维码、二维码、RFID标签等信息的功能。5.1.2.5 EU网元功能应在信息终端设备上实现；EU网元应向用户提供追溯的交互式人机界面。5.1.2.6 SP网元应部署在监管部门的服务器系统上，SP网元应实现支撑利用追溯数据开展对企业的监管功能。5.1.2.7 追溯代理应以用户发起的追溯请求为触发，代替用户完成追溯系统的内部业务处理。5.2 基本服务功能 DCS网元应提供但不限于以下功能：a)追溯标识注册功能；b)追溯事件登记功能；c)追溯信息查询服务。6 数据接口 6.1 基本要求 食品安全电子追溯系统的各个网元之间应通过Internet公共以太网接口互联互通。各网元的物理接口上承载的协议栈应为HTTP或HTTPS协议栈，数据接口应使用基于HTTP/HTTPS协议的JSON格式的消息体传输数据。DCS网元和其它各个网元之间应通过本标准规定的数据接口进行消息交互，实现DCS网元的功能。这些数据接口包括：a)DCS 标识管理接口；b)DCS 事件登记接口；c)DCS 查询接口。6.2 接口原语 基于服务的方式定义数据接口的使用方法。服务响应流程使用了“请求-Request”“指示-Indication”“响应-Response”“确认-Confirm”四条服务原语，原语的顺序见图2。客户端服务器HTTPRequest消息请求-Request指示-IndicationHTTPResponse消息响应-Response确认-Confirm 图2 服务响应流程 DCS标识管理接口应包括：a)DCS 标识注册接口；b)DCS 标识更新接口；c)DCS 标识删除接口。DCS 事件登记接口应包括：a)DCS 主数据登记接口；b)DCS 事件登记接口。DCS查询接口只包括DCS追溯信息查询接口的一个接口。6.3 数据类型 DCS网元接口中所使用到的数据类型见表1。表1 数据类型说明 类型名 类型描述 类型说明 String 文本字符串 内容为所有的有效字符 Number 数字类型 内容由从 0-9 的数字字符，和+-字符组成 List 列表类型 每一项均为一个子数据项，子数据项编码方式与父数据项编码方式相同 Datatime 时间类型 固定格式字符串，格式为 YYYY-MM-DD hh:mm:ss 6.4 调用方式 6.4.1 请求 请求接口应基于HTTP协议，发送的HTTP请求应符合RFC2616的规定。请求接口应使用Get或者Post方法调用目录服务接口。调用方应将请求参数按照消息格式用JSON封装后，封装在HTTP的Request消息的Body中发送出去。6.4.2 响应 请求接口调用成功后，DCS网元应以RFC4825中规定的XML或RFC 4627中规定的JSON格式将处理结果放置在HTTP的Response消息的Body中，返回给调用者。6.5 参数要求 6.5.1 DCS 标识注册接口 6.5.1.1 接口描述 部署在食品生产企业的 IQS 通过可通过 DCS 标识注册接口调用 DCS 网元的标识注册服务。该接口调用方向应为从 IQS 网元到 DCS 网元，接口调用方法应为 HTTP Post；该接口示例参见附录 B.1。6.5.1.2 接口参数 该接口名称为 DCS_IDList_Reg，DCS 标识注册请求接口参数见表 2，DCS 标识注册响应接口参数见表 3。表2 DCS 标识注册请求接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_IDList_Reg 是 CodeList List 单个标识最大长度为 255 所注册的标识列表，可包含多个标识 是 IotISURL String 255 食品生产商 IQS 服务器的 URL 是 Structure String 255 所注册的标识规则 是 表3 DCS 标识注册响应接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 Status String 32 返回值，返回注册结果。参数值规定如下：Succ 成功 NoID 标识不存在 IDReg 标识已注册 Other 其他错误 是 6.5.2 DCS 标识更新接口 6.5.2.1 接口描述 IQS网元应通过DCS标识更新接口实现对指定标识信息的修改。该接口调用方向为从IQS网元到DCS网元，该接口调用方法为 HTTP Post；该接口示例参见附录 B.2。6.5.2.2 接口参数 该接口名称为DCS_ID_Upd，DCS标识更新请求接口参数见表4，DCS标识更新响应接口参数见表5。表4 DCS 标识更新请求接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_ID_Upd 是 ID String 255 所更新的标识 是 NewID String 255 所需更新的标识内容 是 iotISURL String 255 食品生产商 IQS 服务器的 URL 是 表5 DCS 标识更新响应接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 Status String 32 返回值，返回注册结果；参数值规定如下：Succ 成功 NoID 标识不存在 Other 其他错误 是 6.5.3 DCS 标识删除接口 6.5.3.1 接口描述 IQS 网元应通过 DCS 标识删除接口实现对指定标识追溯信息的删除。接口调用方向为从 IQS 网元到DCS 网元，该接口调用方法为 HTTP Post；该接口示例参见附录 B.3。6.5.3.2 接口参数 该接口名称为DCS_ID_Del，DCS标识删除请求接口参数见表6，DCS标识删除响应接口参数见表7。表6 DCS 标识删除请求接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_ID_Del 是 ID string 255 所需删除的标识内容 是 表7 DCS 标识删除响应接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 Status String 32 返回值，返回注册结果；参数值规定如下：Succ 成功 NoID 标识不存在 Other 其他错误 是 6.5.4 DCS 主数据登记接口 6.5.4.1 接口描述 IQS 网元可通过主数据登记接口实现在 DCS 上创建商品的主数据档案，IQS 网元向 DCS 网元登记的商品信息为摘要信息。该接口调用方向为从 IQS 网元到 DCS 网元，该接口调用方法为 HTTP Post；该接口示例参见附录 B.4。6.5.4.2 接口定义 该接口名称为 DCS_MasterData_Reg，DCS 主数据登记请求接口参数见表 8，DCS 主数据登记响应接口参数见表 9。表8 DCS 主数据登记请求接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_MasterData_Reg 是 CodeList List 单个标识最大长度为 255 所注册的标识列表，可包含多个标识 是 IotISURL String 255 iotIS 地址 是 MasterData List 见表 A.1 项目列表，item 类型定义见表A.1 是 表9 DCS 主数据登记响应接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 Status String 32 返回值，返回注册结果。参数值规定如下：Succ 成功 Other 其他错误 是 6.5.5 DCS 事件登记接口 6.5.5.1 接口描述 IQS 网元可通过 DCS 事件登记接口实现事件信息上传。该接口调用方向为从 IQS 网元至 DCS 网元，该接口的调用方法为 HTTP Post。该接口示例参见附录 B.5。6.5.5.2 接口定义 该接口名称为 DCS_Evn_Reg，DCS 事件登记请求接口参数见表 10，DCS 事件登记响应接口参数见表11。表10 DCS 事件登记请求接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_Evn_Reg 是 CodeList List 单个标识最大长度为 255 所注册的标识列表，可包含多个标识 是 IotISURL String 255 iotIS 地址 是 EvtDetail List 见表 A.1 项目列表，item 类型定义见表A.1 是 表11 DCS 事件登记响应接口参数 参数名称 类型 最大长度 Byte 说明 是否必选 Status String 32 返回值，返回注册结果。参数值规定如下：Succ 成功 Other 其他错误 是 6.5.6 DCS 追溯信息查询接口 6.5.6.1 接口描述 追溯代理应通过 DCS 追溯信息查询接口获取标识相关的追溯摘要信息。该接口调用方向为从 IRS到 DCS，该接口调用方法为 HTTP Post；该接口示例参见附录 B.6。6.5.6.2 接口定义 该接口名称为 DCS_Info_Que，DCS 追溯信息查询请求接口参数见表 12，DCS 追溯信息查询响应接口参数见表 13。表12 DCS 追溯信息查询请求信息 参数名称 类型 最大长度 Byte 说明 是否必选 MessageName String 32 取值为 DCS_Info_Que 是 ID String 255 被查询标识 是 表13 DCS 追溯信息查询响应参数 参数名称 类型 最大长度 Byte 说明 是否必选 EvtList List 见表 14 事件信息列表，evt 类型定义见表 14 是 表14 evt 类型定义 参数名称 类型 最大长度 Byte 说明 是否必选 iotISURL String 255 食品经营企业 IQS 服务器的URL 列表 是 EvtDetail List 见表 A.1 服务资源列表 是 A A 附 录 A（规范性附录）Item 类型参数 Item类型参数见表A.1。表A.1 Item 类型参数 参数名称 类型 最大长度 Byte 说明 是否必选 ItemName String 32 字段取值见表 A.2 是 ItemValue String 255 字段取值见表 A.2 是 Item类型参数取值见表A.2。表A.2 Item 类型参数取值 ItemName 取值 类型 ItemValue 内容填写说明 eventTime Datatime 事件发生时间 recordTime Datatime（选填）这个事件被 IQS 记录的日期时间。在事件提交到 IQS 捕获接口时必须忽略，由 IQS 自动记录；在查询时可以获得 eventTimeZoneOffset String 事件发生地点时区与 UTC 时区的差值。这个字段的值应是字符串，以+或者-开头，后两位是在 00 到 14 之间（包括 00，14）的数字，接着是一个冒号，后面是两位在 00 到 59 之间（包括 00 和 59）的数字，若前两位是 14，后两位必须是 00；比如，+05:30 表示时间发生地的当地时间和 UTC 相比迟 5 个小时 30 分钟（也就是 UTC 的午夜是当地时间的早晨 5:30）action String 事件导致的物品状态变化情况；ADD：增加;DELETE：移除；OBSERVE：不变 bizStep String 业务步骤 ID，参见 DB32/T XXXX-XXXX disposition String 物品状态 ID，参见 DB32/T XXXX-XXXX readPoint String 事件发生时刻的业务位置 ID，应为 URN 格式的网络位置标识 bizLocation String 事件发生后物品所在业务位置 ID，应为 URN 格式的网络位置标识 B B 附 录 B（资料性附录）数据接口应用示例 B.1 DCS标识注册接口应用示例 B.1.1 HTTP-Request消息的JSON消息体 var JSONObject=MessageName:DCS_IDList_Reg,CodeList:ID:urn:cniotroot:id:obj:,ID:urn:cniotroot:id:obj:,IotISURL:http:/ B.1.2 HTTP-Response消息的JSON消息体 var JSONObject=Status:Succ B.2 DCS标识更新接口应用示例 B.2.1 HTTP-Request消息的JSON消息体 var JSONObject=MessageName:DCS_ID_Upd,ID:urn:cniotroot:id:obj:,NewID:urn:cniotroot:id:obj:，IotISURL:http:/ B.2.2 HTTP-Response消息的JSON消息体 var JSONObject=Status:Succ B.3 DCS标识删除接口应用示例 B.3.1 HTTP-Request消息的JSON消息体 var JSONObject=MessageName:DCS_ID_Del,ID:urn:cniotroot:id:obj: B.3.2 HTTP-Response消息的JSON消息体 var JSONObject=Status:Succ B.4 DCS主数据登记接口应用示例 B.4.1 HTTP-Request消息的JSON消息体 var JSONObject=MessageName:DCS_MasterData_Reg,CodeList:ID:urn:cniotroot:id:obj:,ID:urn:cniotroot:id:obj:,iotISURL:http:/ 13:24:35,EvePos:Nanjing XinGang Park No.12,AlarmContent:Temperature too high B.4.2 HTTP-Response消息的JSON消息体 var JSONObject=Status:Succ B.5 DCS事件登记接口应用示例 B.5.1 HTTP-Request消息的JSON消息体 var JSONObject=MessageName:DCS_Evn_Reg,CodeList:ID:urn:cniotroot:id:obj:,ID:urn:cniotroot:id:obj:,iotISURL:http:/ 13:24:35,EvePos:Nanjing XinGang Park No.12,AlarmContent:Temperature too high B.5.2 HTTP-Response消息的JSON消息体 var JSONObject=Status:Succ B.6 DCS追溯信息查询接口应用示例 B.6.1 HTTP-Request消息的JSON消息体:var JSONObject=MessageName:DCS_Info_Que,ID:urn:cniotroot:id:obj:,EvtList:iotISURL:http:/ 13:24:35,EvePos:Nanjing XinGang Park No.12,AlarmContent:Temperature too high B.6.2 HTTP-Response消息的JSON消息体:var JSONObject=Status:Succ _