DB52 T 1541.4-2021 政务数据平台 第4部分：接口规范.pdf

1、ICS 01.040.03A 12 DB52贵 州 省 地 方 标 准DB52/T 1541.4 2021政 务 数 据 平 台 第 4部 分 ： 接 口 规 范 Government data platform Part4： Interface specification 2021 -05- 17发 布 2021- 09-01实 施贵 州 省 市 场 监 督 管 理 局 发 布 DB52/T 1541.42021 I 目 次前 言 .II1 范 围 .12 规 范 性 引 用 文 件 .13 术 语 和 定 义 .14 缩 略 语 .25 基 本 要 求 .26 接 口 组 成 .27 接

2、口 要 求 .3 8 接 口 安 全 .9附 录 A （ 资 料 性 ） 认 证 授 权 服 务 接 口 JSON Schema示 例 .10附 录 B （ 资 料 性 ） 组 织 新 增 接 口 JSON Schema示 例 .11附 录 C （ 资 料 性 ） 用 户 新 增 接 口 JSON Schema示 例 .12附 录 D （ 资 料 性 ） 数 据 资 源 目 录 接 口 的 接 口 信 息 JSON Schema 示 例 .13附 录 E （ 资 料 性 ） 数 据 资 源 目 录 接 口 信 息 描 述 对 象 参 数 表 .15附 录 F （ 资 料 性 ） 数 据 资 源

3、 目 录 接 口 的 目 录 信 息 JSON Schema 描 述 示 例 .16附 录 G （ 资 料 性 ） 数 据 资 源 目 录 描 述 对 象 参 数 表 .18附 录 H （ 资 料 性 ） 政 务 数 据 平 台 接 口 返 回 JSON Schema示 例 .19附 录 I （ 资 料 性 ） 政 务 数 据 平 台 接 口 返 回 参 数 表 .21 DB52/T 1541.4 2021 II 前 言 本文件按照GB/T 1.1-2020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起 草。 本文件是DB52/T 1541的第4部分。 DB52/T 1541已经

4、发布一下部分： 第2部分：数据归集规范； 第3部分：数据存储规范； 第4部分：接口规范； 第6部分：面向全网搜索应用的数据处理规范。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。 本文件由贵州省大数据发展管理局提出并归口。 本文件起草单位：贵州省机械电子产品质量检验检测院、贵州中软云上数据技术服务有限公司、 贵 州省信息中心 、 贵州省量子信息和大数据应用技术研究院 。 本文件主要起草人 ：朱小洪、宿睿智、刘彦嘉、王嘉卉、徐凯琳、田野、秦晓东、邵建平、 潘伟杰、韩朱旸、冯丹妮、尚志刚、杨昶、李怡然、吴明娅、石睿、曾映菊、唐昶、张洋、姚茂峰、 陆莹、孙瑾。 DB

5、52/T 1541.4 2021 1 政务数据平台 第 4 部分：接口规范 1 范围 本文件规定了政务数据平台数据接口的术语和定义、缩略语、基本要求、接口组成、接口要求和接 口安全。 本文件适用于政务数据平台接口的设计和应用。 2 规范性引用文件 本文件没有规范性引用文件。 3 术语和定义 下列术语和定义适用于本文件。 3.1 接口 interface 基于应用程序的服务能力封装成接口，并通过API网关开放给客户端调用。 3.2 数据 data 对事实、概念或指令的一种形式化表示，适用于以人工或自动方式进行通信、解释或处理。 来源：DB52/T 1239 .1-2017，3.1 3.3 政务数

6、据资源目录 directory of government data resources 通过对政务数据资源依据规范的元数据描述，按照一定的分类方法进行排序和编码的一组信息,用 以描述各个政务数据资源的特征，以便于对政务数据资源的检索、定位与获取。 3.4 政务数据提供方 government d ata provider 基于统一数据共享交换平台，利用各种技术向其他政务部门、事业单位、企业或公众提供政务数据 的实体。 DB52/T 1541.42021 2 3.5 访 问 令 牌 access token访 问 控 制 操 作 主 体 的 系 统 对 象 。4 缩 略 语下 列 缩 略 语

7、适 用 于 本 文 件 。API： 应 用 程 序 编 程 接 口 （ Application Programming Interface）HTTP： 超 文 本 传 输 协 议 （ Hyper Text Transfer Protocol）HTTPS： 超 文 本 传 输 安 全 协 议 （ Hyper Text Transfer Protocol over SecureSocket Layer）JSON： 轻 量 级 的 数 据 交 换 格 式 （ Javascript Object Notation）REST： 一 种 网 络 应 用 程 序 的 设 计 风 格 和 开 发 方 式 （

8、Repersentational State Transfer） 5 基 本 要 求5.1 应 采 用 HTTP/HTTPS 作 为 传 输 协 议 。5.2 应 采 用 JSON作 为 消 息 的 封 装 格 式 。5.3 应 提 供 服 务 请 求 成 功 、 失 败 等 各 种 情 况 的 接 口 返 回 状 态 码 。5.4 应 支 持 跨 语 言 、 跨 操 作 系 统 调 用 。6 接 口 组 成政 务 数 据 平 台 接 口 主 要 包 括 ： 认 证 授 权 服 务 接 口 、 组 织 接 口 、 用 户 接 口 、 数 据 资 源 目 录 接 口 。 政 务数 据 平 台 接

9、 口 组 成 见 图 1。 图 1 政 务 数 据 平 台 接 口 组 成 图 DB52/T 1541.42021 3 7 接口要求7.1 认证授权服务接口接口描述：政务数据提供方接入政务数据平台应调用认证授权服务接口。通过平台认证授权服务接口进行身份验证，验证成功后接口返回的授权访问令牌，政务数据提供方操作政务数据平台接口应携带访问令牌，进行正常会话交互。 接口地址：/api/auth_service。接口类型：post。请求参数：认证授权服务接口请求参数见表1。请求示例：见附录A。返回参数：见附录I 表I.1。返回示例：见附录H。 表 1 认证授权服务接口请求参数表参数名称 类型 是否必填

10、 说明access_key string 是 政务数据平台分配给政务数据提供方的唯一标识access_secret string 是 政务数据平台分配给政务数据提供方的密钥username string 是 政务数据平台分配给政务数提供方的用户账户名称password string 是 政务数据平台分配给政务数据提供方的用户账户密码7.2 组织接口7.2.1 组织新增接口接口描述：政务数据提供方调用政务数据平台组织新增接口，获取政务数据平台返回的组织ID，根据组织ID进行政务数据提供方系统和政务数据平台交互。 接口地址：/api/add/organization。接口类型：post。请求参数：

11、同步组织机构请求参数见表2。请求示例：见附录B。返回参数：见附录I 表I.1。返回示例：见附录H。 表 2 同步组织机构请求参数表参数名称 类型 是否必填 说明addType int 是 操作类型：1表示新增trustNo int 是 统一社会信用代码 groupShortName string 是 组织简称groupName string 是 组织名称regionName string 是 组织所属地区orgPostNo int 是 组织区划编号group_level int 是 级别：401 省直，402 市州super_org int 是 父级组织编号 DB52/T 1541.42021

12、 4 7.2.2 组 织 编 辑 接 口接 口 描 述 ： 编 辑 组 织 机 构 信 息 。接 口 地 址 ： /api/add/organization。接 口 类 型 ： post。请 求 参 数 ： 组 织 机 构 编 辑 请 求 参 数 见 表 3。请 求 示 例 ： 见 附 录 B。返 回 参 数 ： 见 附 录 I 表 I.1。返 回 示 例 ： 见 附 录 H。 表 3 组 织 机 构 编 辑 请 求 参 数 表 参 数 名 称 类 型 是 否 必 填 说 明addType int 是 操 作 类 型 ： 2 表 示 编 辑trustNo int 是 统 一 社 会 信 用 代

13、 码groupShortName string 是 组 织 简 称groupName string 是 组 织 名 称regionName string 是 组 织 所 属 地 区orgPostNo int 是 组 织 区 划 编 号group_level int 是 级 别 ： 401 省 直 ， 402 市 州super_org int 是 父 级 组 织 编 号7.2.3 组 织 查 询 接 口接 口 描 述 ： 政 务 数 据 提 供 方 查 询 政 务 组 织 机 构 信 息 。 接 口 地 址 ： /api/organization/query。接 口 类 型 ： get。请 求

14、参 数 ： 组 织 机 构 查 询 接 口 请 求 参 数 见 表 4。请 求 示 例 ： http:/ip+port/api/organization/query?org_name=组 织 名 称&org_id=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。返 回 参 数 ： 见 附 录 I 表 I.1。返 回 示 例 ： 见 附 录 H。 表 4 组 织 机 构 查 询 接 口 请 求 参 数 表参 数 名 称 类 型 是 否 必 填 说 明org_id string 是 组 织 id org_name string 是 组 织 名 称7.3 用 户 接 口7.3.1

15、用 户 新 增 接 口接 口 描 述 ： 政 务 数 据 提 供 方 调 用 用 户 新 增 接 口 ， 同 步 组 织 机 构 用 户 信 息 到 政 务 数 据 平 台 。接 口 地 址 ： /api/add/user。接 口 类 型 ： post。请 求 参 数 ： 组 织 机 构 用 户 新 增 请 求 参 数 见 表 5。 DB52/T 1541.42021 5 请求示例：见附录C。返回参数：见附录I 表I.1。返回示例：见附录H。 表 5 组织机构用户新增请求参数表参数名称 类型 是否必填 说明org_id string 是 组织 idaddType int 是 操作类型：1表示新

16、增userName string 是 用户名trueName string 是 用户真实姓名roIds string 否 用户角色 mobile string 是 联系电话7.3.2 用户编辑接口接口描述：政务数据提供方编辑政务组织机构用户信息。接口地址：/api/add/user。接口类型：post。请求参数：组织机构用户编辑请求参数见表6。请求示例：见附录C。返回参数：见附录I 表I.1。返回示例：见附录H。 表 6 组织机构用户编辑请求参数表 参数名称 类型 是否必填 说明org_id string 是 组织 idaddType int 是 操作类型：1表示新增userName stri

17、ng 是 用户名trueName string 是 用户真实姓名roIds string 是 用户角色7.3.3 用户查询接口接口描述：政务数据提供方查询政务数据平台组织机构用户信息。接口地址：/api/query/user。接口类型：get。请求参数：用户查询见请求参数表7。 请求示例：http:/ip+port/api/user/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。返回参数：见附录I 表I.1。返回示例：见附录H。 表 7 用户查询请求参数表参数名称 类型 是否必填 说明userId string 是 用户 id DB52/T 154

18、1.42021 6 7.4 数 据 资 源 目 录 接 口7.4.1 数 据 资 源 目 录 新 增 接 口接 口 描 述 ： 政 务 数 据 提 供 方 同 步 政 务 组 织 机 构 的 数 据 资 源 目 录 信 息 到 政 务 数 据 平 台 。接 口 地 址 ： /api/add/resource。接 口 类 型 ： post请 求 参 数 ： 数 据 资 源 目 录 新 增 请 求 参 数 见 表 8。请 求 示 例 ： 见 附 录 D。返 回 参 数 ： 见 附 录 I 表 I.1。返 回 示 例 ： 见 附 录 H。 表 8 数 据 资 源 目 录 新 增 请 求 参 数 表

19、参 数 名 称 类 型 是 否 必 填 说 明id string 是 数 据 资 源 目 录 idindustryId string 是 行 业 idorgId string 是 组 织 idtopicId string 是 主 题 iduserId string 是 用 户 idaddType int 是 操 作 类 型 ： 1 表 示 新 增apiData jsonObject 是 接 口 信 息 描 述 见 图 2，数 据 结 构 见 附 录 D、 附 录 Edirectory jsonObject 是 目 录 信 息 描 述 见 图 3数 据 结 构 见 附 录 F、 附 录 G in

20、dustry string 是 行 业openAttribute int 是 开 放 属 性 ： 1 有 条 件 开 放 ； 2 无 条 件 开 放 ； 3 不 予 开 放serviceName string 是 服 务 名 称shareAttribute int 是 共 享 属 性 ： 1 有 条 件 共 享 ； 2 无 条 件 共 享 ； 3 不 予 共 享topic string 是 主 题uniscid string 是 统 一 社 会 信 用 代 码 DB52/T 1541.42021 7图 2 接口信息描述组成结构图 DB52/T 1541.42021 8 图 3 目 录 信 息

21、描 述 组 成 结 构 图7.4.2 数 据 资 源 目 录 编 辑 接 口接 口 描 述 ： 政 务 数 据 提 供 方 编 辑 数 据 资 源 目 录 信 息 。接 口 地 址 ： /api/add/resource。接 口 类 型 ： post。请 求 参 数 ： 数 据 资 源 目 录 编 辑 请 求 参 数 见 表 9。请 求 示 例 ： 见 附 录 D。返 回 参 数 ： 见 附 录 I 表 I.1。返 回 示 例 ： 见 附 录 H。 表 9 数 据 资 源 目 录 编 辑 请 求 参 数 表 参 数 名 称 类 型 是 否 必 填 说 明id string 是 数 据 资 源

22、目 录 iduserId string 是 用 户 idaddType int 是 操 作 类 型 ： 2表 示 编 辑openAttribute int 是 开 放 属 性 ： 1 有 条 件 开 放 ； 2 无 条 件 开 放 ； 3 不 予 开 放shareAttribute int 是 共 享 属 性 ： 1 有 条 件 共 享 ； 2 无 条 件 共 享 ； 3 不 予 共 享7.4.3 数 据 资 源 目 录 查 询 接 口接 口 描 述 ： 政 务 数 据 提 供 方 查 询 数 据 资 源 目 录 信 息 。接 口 地 址 ： /api/resource/query。接 口 类

23、 型 ： post。请 求 参 数 ： 数 据 资 源 目 录 查 询 请 求 参 数 见 表 10。 请 求 示 例 ： http:/ip+port/api/resource/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。 DB52/T 1541.42021 9 返回参数：见附录I 表I.1。返回示例：见附录H。 表 10 数据资源目录查询请求参数表参数名称 类型 是否必填 说明id string 是 数据资源目录 iduserId string 是 用户 id8 接口安全8.1 对请求的合法性进行校验。8.2 对请求的数据进行校验。 8.3 对

24、请求实现黑明单与白名单拦截。8.4 对请求实现用户使用接口的流量限制。 DB52/T 1541.42021 10 AA附 录 A（ 资 料 性 ）认 证 授 权 服 务 接 口 JSON Schema 示 例下 面 给 出 认 证 授 权 服 务 接 口 JSON Schema示 例 。示 例 ： $schema: http:/json-schema.org/draft-07/schema, $id: object,title: The root schema,examples: app_key: C3kFcJP5Pw5w13nBX2GCh03zSrn8p7BA,app_secret: rmn

25、nkSkWfx0A7w6n13bKrwPGaM0dEQr6,username: test,password: 8vJDXhG2waQ5rAxG, required: app_key,app_secret,username,password DB52/T 1541.42021 11 BB附 录 B（资料性）组织新增接口 JSON Schema 示例下面给出组织新增接口JSON Schema示例。示例： $schema: http:/json-schema.org/draft-07/schema, $id: object,title: The root schema,description: Th

26、e root schema comprises the entire JSON document.,default: ,examples: addType: 1,trustNo: 91370200163562681G,groupShortName: 测试,groupName: 组织新增测试, regionName: test,orgPostNo: KXRay9teJN0V93kvgk,group_level: 401,super_org: 100,required: addType,trustNo,groupShortName,groupName, regionName,orgPostNo,g

27、roup_level,super_org DB52/T 1541.42021 12 CC附 录 C（ 资 料 性 ）用 户 新 增 接 口 JSON Schema示 例下 面 给 出 用 户 新 增 接 口 JSON Schema示 例 。示 例 ： $schema: http:/json-schema.org/draft-07/schema, $id: object,title: The root schema,description: The root schema comprises the entire JSON document.,examples: addType: 1,userN

28、ame: example,trueName: 示 例 ,roIds: sdfsdf,org_id: ssKXRauteJN0V93krd, mobile: KXRay9teJN0V93kvgk,required: addType,userName,trueName,roIds,org_id,mobile DB52/T 1541.42021 13 DD附 录 D（资料性）数据资源目录接口的接口信息 JSON Schema示例数据资源目录接口的接口信息JSON Schema示例。示例： $schema: http:/json-schema.org/draft-07/schema, $id: obj

29、ect,title: The root schema,description: The root schema comprises the entire JSON document.,required: apiData,properties: apiData: $id: #/properties/apiData,type: object, title: The apiData schema,description: An explanation about the purpose of this instance.,default: ,examples: bodyType: 0,createT

30、ime: 1590647639923,description: 描述,requestDemo: ?pageIndex=1&pageSize=50,requestMode: 1,requestParam: description: 分页，当前页,must: 0,name: pageIndex,type: 1,responseDemo: ,responseParam: description: 号码, DB52/T 1541.42021 14 name: id,type: 2,responseType: 1,resultCode: description: 成 功 ,name: 200, upda

31、teTime: 1590647639923,url: http:/ip+port/,required: bodyType,createTime,description,requestDemo,requestMode,requestParam, responseDemo,responseParam,responseType,resultCode,updateTime,url DB52/T 1541.42021 15 EE附 录 E（资料性）数据资源目录接口信息描述对象参数表数据资源目录接口信息描述对象参数表见表E.1。 表 E.1 数据资源目录接口信息描述对象参数表参数名称 类型 是否必填 说明

32、 bodyType integer 是 接口类型createTime integer 是 创建时间description string 是 用途描述requestDemo string 是 服务调用示例requestMode integer 是 请求方法requestParam array 是 请求参数responseDemo string 是 响应示例responseParam array 是 响应参数responseType integer 是 响应类型resultCode array 是 状态码说明 updateTime integer 是 更新时间url string 是 接口服务地址

33、 DB52/T 1541.42021 16 FF附 录 F（ 资 料 性 ）数 据 资 源 目 录 接 口 的 目 录 信 息 JSON Schema 描 述 示 例下 面 给 出 数 据 资 源 目 录 接 口 的 目 录 信 息 JSON Schema描 述 示 例 。示 例 ： $schema:http:/json-schema.org/draft-07/schema, $id: root schema,description:The root schema comprises the entire JSON document.,required:directory,properties

34、:directory:$id:#/properties/directory,type:object, title:The directory schema,description:An explanation about the purpose of this instance.,default:,examples: infoItems: description:身 份 证 号 码 ,length:100,name:id, type:varchar,serviceName:饮 水 安 全 ,system:system:回 归 测 试 ,systemId:710b8d8c-e868-4b55-9

35、e4d-d2b50ad78521, DB52/T 1541.42021 17 required:infoItems,serviceName,system DB52/T 1541.42021 18 GG附 录 G（ 资 料 性 ）数 据 资 源 目 录 描 述 对 象 参 数 表数 据 资 源 接 口 描 述 对 象 参 数 表 见 表 G.1。表 G.1 数 据 资 源 目 录 描 述 对 象 参 数 表参 数 名 称 类 型 是 否 必 填 说 明 infoItems array 是 信 息 项serviceName string 是 服 务 名 称system object 是 系 统 名

36、 称 DB52/T 1541.42021 19 HH附 录 H（资料性）政务数据平台接口返回 JSON Schema 示例下面给出政务数据平台接口返回JSON Schema示例。示例： $schema: http:/json-schema.org/draft-07/schema, $id: object,title: The root schema,examples: status: 成功返回状态码值或失败返回状态码值,message: 成功时状态码说明或失败时状态码值说明,required: status, message,properties: status: $id: #/propert

37、ies/status,type: string,title: The status schema,description: An explanation about the purpose of this instance.,default: ,examples: 成功返回状态码值或失败返回状态码值 ,message: $id: #/properties/message,type: string,title: The message schema,description: An explanation about the purpose of this instance.,default: ,examples: 成功时状态码说明或失败时状态码值说明 DB52/T 1541.42021 20 ,additionalProperties: true DB52/T 1541.42021 21 II附 录 I（资料性）政务数据平台接口返回参数表政务数据平台接口返回参数表见表I.1。 表 I.1 政务数据平台接口返回参数表参数名称 类型 是否必填 说明 status integer 是 成功返回状态码值或失败返回状态码值message String 是 成功时状态码说明或失败时状态码值说明_ DB52/T 1541.4-2021