DB63 T 2019-2022 市场监管大数据平台接口规范.pdf

1、ICS 01.080.30 CCS L 04 DB63 青 海 省 地 方 标 准 DB 63/T 20192022 市场监管大数据平台接口规范 2022 - 03 - 10发布 2022 - 04 - 10实施 青海省市场监督管理局 发 布 DB63/T 20192022 I 目 次 前言 . II 1 范围 . 1 2 规范性引用文件 . 1 3 术语和定义 . 1 3.1 接口 . 1 3.2 协议 . 1 4 缩略语 . 1 5 接口总体要求 . 1 5.1 接口方式 . 1 5.2 接口返回数据格式 . 1 5.3 接口调用地址 . 2 5.4 部分接口调用参数说明 . 2 6 统一

2、身份认证接口 . 2 6.1 获取授权码接口 . 2 6.2 获取访问令牌接口 . 2 6.3 刷新令牌接口 . 3 6.4 退出登录接口 . 3 7 数据上传接口 . 4 8 数据更新接口 . 5 9 数据删除接口 . 5 10 数据查询接口 . 6 DB63/T 20192022 II 前 言 本文件按照GB/T 1.1-2020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起 草。 本文件由青海省市场监督管理局提出并归口。 本文件主要起草单位：青海省市场监督管理局信息中心。 本文件主要起草人：马玉成、王向文、王逸轩、李瑛、周继辉、何海超、董雪彤、李伟、刘宇静、 汪国孝。 本文

3、件由青海省市场监督管理局监督实施。DB63/T 20192022 1 市场监管大数据平台接口规范 1 范围 本文件规定了市场监管大数据平台接口总体要求、统一身份认证、数据上传、数据更新、 数据删除、 数据查询接口规范。 本文件适用于市场监管业务系统和其它信息系统与市场监管大数据平台之间通过接口进行数据共 享和传输。 2 规范性引用文件 本文件没有规范性引用文件。 3 术语和定义 下列术语和定义适用于本文件。 3.1 接口 进行信息交换时通信双方需要遵从的通信方式和要求。 3.2 协议 服务端和客户端必须共同遵循的一组约定。 4 缩略语 下列缩略语适用于本文件。 HTTPS：超文本传输安全协议（

4、Hyper Text Transfer Protocol over SecureSocket Layer） JSON：JavaScript 对象标记语言（JavaScript Object Notation） RESTful：REST风格的网络接口 5 接口总体要求 5.1 接口方式 市场监管大数据平台的接口统一采用 RESTful 架构风格的 Web 服务。 接口访问采用HTTPS协议的GET和POST方式。 DB63/T 20192022 2 5.2 接口返回数据格式 接口返回数据采用JSON格式。详见每个接口的详细描述。 5.3 接口调用地址 本规范接口调用地址中的“https:/ip:

5、port”在实际调用时，需要把其中的“ip”和“port”修 改为市场监管大数据平台提供的真实IP地址和访问端口。 5.4 部分接口调用参数说明 dataName：数据对象名称。外部对接系统可以使用的数据对象名称需要在使用前向市场监管大数据 平台申请。如：“食品从业人员信息”、“药品零售企业信息”等。 dataValue：描述一个或多个数据对象实例的JSON字符串。该JSON字符串包含一个数组对象，每个 数组元素是一个数据对象实例。如： 单位名称:蜀香火锅店, 负责人:张大明 6 统一身份认证接口 6.1 获取授权码接口 调用地址：https:/ip:port/OAuth/Authorize

6、调用方式：HTTP的GET方法。 调用参数：见表1。 表1 获取授权码接口调用参数 参数名 类型 必填 说明 举例 client_id 字符串 是 应用向大数据平台申请的client_id 75ef2134-981b-4 56c-f63c-08d882c de193 client_secret 字符串 是 应用向大数据平台申请的client_ secret 78juqyes scope 字符串 是 应用向大数据平台请求的属性 app redirect_uri 字符串 是 认证完成并且用户对应用授权后跳转的地 址，此地址可以得到grant_code授权码 https:/ip:port /call

7、back response_type 字符串 是 值固定为“code” code 返回值：JSON对象，对象的属性说明和示例如下。 grant_code:3092 / 获取到的授权码 6.2 获取访问令牌接口 调用地址：https:/ip:port/OAuth/Access_Token DB63/T 20192022 3 调用方式：HTTP的GET方法。 调用参数：见表2。 表2 获取访问令牌接口调用参数 参数名 类型 必填 说明 举例 client_id 字符串 是 应用向大数据平台申请的client_id 75ef2134-981b-4 56c-f63c-08d882c de193 cli

8、ent_secret 字符串 是 应用向大数据平台申请的client_ secret 78juqyes scope 字符串 是 应用向大数据平台请求的属性 app redirect_uri 字符串 是 认证完成并且用户对应用授权后跳转的地 址 https:/ip:port /callback grant_type 字符串 是 值固定为“authorization_code” authorization_c ode code 字符串 是 通过“获取授权码接口”获取到的授权码 3092 返回值：JSON对象，对象的属性说明和示例如下。 expires_in: 7200, / 令牌有效期，单位“秒”

9、 token_type: Bearer, / 获得的令牌类型为Bearer access_token: a23098ca-8584-4d76-f63b-08d882cde193 / 访问令牌 6.3 刷新令牌接口 调用地址：https:/ip:port/OAuth/Refresh_Token 调用方式：HTTP的GET方法。 调用参数：见表3。 表3 刷新令牌接口调用参数 参数名 类型 必填 说明 举例 client_id 字符串 是 应用向大数据平台申请的client_id 75ef2134-981b-4 56c-f63c-08d882c de193 access_token 字符串 是 访

10、问令牌 a23098ca-8584-4 d76-f63b-08d882c de193 返回值：JSON对象，对象的属性说明和示例如下。 expires_in: 7200, / 令牌有效期，单位“秒” token_type: Bearer, / 获得的令牌类型为Bearer access_token: 82553e7e-2647-4307-b8a0-08d840293f1a / 新的访问令牌 6.4 退出登录接口 DB63/T 20192022 4 调用地址：https:/ip:port/OAuth/Logout 调用方式：HTTP的GET方法。 调用参数：见表4。 表4 退出登录接口调用参数

11、参数名 类型 必填 说明 举例 tk 字符串 是 访问令牌 a23098ca-8584-4 d76-f63b-08d882c de193 redirect_uri 字符串 是 退出登陆后跳转的地址 https:/ip:port /home 返回值：无，直接跳转redirect_uri指定的地址。 7 数据上传接口 调用地址：https:/ip:port/data/add 调用方式：HTTP的POST方法。 调用参数：见表5。 表5 数据上传接口调用参数 参数名 类型 必填 说明 举例 tk 字符串 是 访问令牌 a23098ca-8584-4 d76-f63b-08d882c de193 da

12、taName 字符串 是 数据对象名称 食品经营许可证 dataValue 字符串 是 描述一个或多个数据对象实例的JSON字符 串 单位名称:蜀香 火锅店, 负责人:张大明 , 单位名称:马学 军牛肉面, 负责人:马学福 返回值：JSON对象，对象的属性说明和示例如下。 Success: true, / 请求的操作是否成功。调用本接口时传递的一个或多个数据对象实例全 部上传成功时才会返回true。 Errors: , / 当Success为true时返回空数组； DB63/T 20192022 5 / 当Success为false时平台返回1个或多个错误信息字符串。如：参数 dataValu

13、e的值不是正确的JSON格式！ Messages: , / 当Success为false时返回空数组； / 当Success为true时平台返回0个、1个或多个信息字符串。如：上传数 据成功！ Data: 73cfd5d3-7195-4f85-f63d-08d882cde193, ac5a260c-b01f-4589-f63e-08d882cde193 / 当Success为true时返回上传的每个数据对象实例的id组成的数组； 8 数据更新接口 调用地址：https:/ip:port/data/update 调用方式：HTTP的POST方法。 调用参数：见表6。 表6 数据更新接口调用参数

14、参数名 类型 必填 说明 举例 tk 字符串 是 访问令牌 a23098ca-8584-4 d76-f63b-08d882c de193 dataName 字符串 是 数据对象名称 食品经营许可证 dataValue 字符串 是 描述一个或多个数据对象实例更新的JSON 字符串。操作会更新ID指定的数据对象实例 的相应属性的值。所以，每个对象实例描述 中必须包含ID属性和需要更新的属性及其 对应的值。 ID:73cfd5d3-7 195-4f85-f63d-08 d882cde193, 负责人:李文才 返回值：JSON对象，对象的属性说明和示例如下。 Success: true, / 请求的操

15、作是否成功。调用本接口时传递的一个或多个数据对象实例全 部更新成功时才会返回true。 Errors: , / 当Success为true时返回空数组； / 当Success为false时平台返回1个或多个错误信息字符串。如：参数 dataValue的值不是正确的JSON格式！ Messages: / 当Success为false时返回空数组； / 当Success为true时平台返回0个、1个或多个信息字符串。如：更新数 据成功！ 9 数据删除接口 DB63/T 20192022 6 调用地址：https:/ip:port/data/delete 调用方式：HTTP的POST方法。 调用参数

16、见表7。 表7 数据删除接口调用参数 参数名 类型 必填 说明 举例 tk 字符串 是 访问令牌 a23098ca-8584-4 d76-f63b-08d882c de193 dataName 字符串 是 数据对象名称 食品经营许可证 dataValue 字符串 是 描述一个或多个数据对象实例删除的JSON 字符串。操作会删除ID指定的数据对象实 例。所以，每个对象实例描述中必须包含ID 属性。 ID:73cfd5d3-7 195-4f85-f63d-08 d882cde193 , ID:ac5a260c-b 01f-4589-f63e-08 d882cde193 返回值：JSON对象，对象

17、的属性说明和示例如下。 Success: true, / 请求的操作是否成功。调用本接口时传递的一个或多个数据对象实例全 部删除成功时才会返回true。 Errors: , / 当Success为true时返回空数组； / 当Success为false时平台返回1个或多个错误信息字符串。如：参数 dataValue的值不是正确的JSON格式！ Messages: / 当Success为false时返回空数组； / 当Success为true时平台返回0个、1个或多个信息字符串。如：删除数 据成功！ 10 数据查询接口 调用地址：https:/ip:port/data/query 调用方式：HT

18、TP的POST方法。 调用参数：见表8。 DB63/T 20192022 7 表8 数据查询接口调用参数 参数名 类型 必填 说明 举例 tk 字符串 是 访问令牌 a23098ca-8584-4d76-f 63b-08d882cde193 dataName 字符串 是 数据对象名称 食品经营许可证 dataValue 字符串 是 描述一个或多个数据对象实例查询的 JSON字符串。操作会查询ID指定的数 据对象实例。所以，每个对象实例描 述中必须包含ID属性。 ID:73cfd5d3-7195-4 f85-f63d-08d882cde193 , ID:ac5a260c-b01f-4 589-f

19、63e-08d882cde193 返回值：JSON对象，对象的属性说明和示例如下。 Success: true, / 请求的操作是否成功。调用本接口时传递的一个或多个数据对象实例全 部查询成功时才会返回true。 Errors: , / 当Success为true时返回空数组； / 当Success为false时平台返回1个或多个错误信息字符串。如：参数 dataValue的值不是正确的JSON格式！ Messages: , / 当Success为false时返回空数组； / 当Success为true时平台返回0个、1个或多个信息字符串。如：查询数 据成功！ Data: ID:73cfd5d3-7195-4f85-f63d-08d882cde193, 单位名称:*火锅店, 负责人:张某某 , ID:ac5a260c-b01f-4589-f63e-08d882cde193, 单位名称:*牛肉面, 负责人:马某某 _