1、ICS 01.040.03A 12DB52贵州省地方标准DB52/T 1541.42021政务数据平台 第 4 部分：接口规范Government data platform Part4：Interface specification2021 - 05 - 17 发布2021 - 09 - 01 实施贵州省市场监督管理局发 布DB52/T 1541.42021I目次前言.II1范围.12规范性引用文件.13术语和定义.14缩略语.25基本要求.26接口组成.27接口要求.38接口安全.9附录 A（资料性）认证授权服务接口 JSONSchema 示例.10附录 B（资料性）组织新增接口 JSON
2、Schema 示例.11附录 C（资料性）用户新增接口 JSONSchema 示例.12附录 D（资料性）数据资源目录接口的接口信息 JSONSchema 示例.13附录 E（资料性）数据资源目录接口信息描述对象参数表.15附录 F（资料性）数据资源目录接口的目录信息 JSONSchema 描述示例.16附录 G（资料性）数据资源目录描述对象参数表.18附录 H（资料性）政务数据平台接口返回 JSONSchema 示例.19附录 I（资料性）政务数据平台接口返回参数表.21 DB52/T 1541.42021 II 前 言 本文件按照GB/T 1.1-2020标准化工作导则 第1部分：标准化文
3、件的结构和起草规则的规定起草。 本文件是DB52/T 1541的第4部分。DB52/T 1541已经发布一下部分： 第2部分：数据归集规范； 第3部分：数据存储规范； 第4部分：接口规范； 第6部分：面向全网搜索应用的数据处理规范。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。 本文件由贵州省大数据发展管理局提出并归口。 本文件起草单位：贵州省机械电子产品质量检验检测院、贵州中软云上数据技术服务有限公司、贵州省信息中心、贵州省量子信息和大数据应用技术研究院。 本文件主要起草人：朱小洪、宿睿智、刘彦嘉、王嘉卉、徐凯琳、田野、秦晓东、邵建平、 潘伟杰、韩朱旸、冯丹
4、妮、尚志刚、杨昶、李怡然、吴明娅、石睿、曾映菊、唐昶、张洋、姚茂峰、陆莹、孙瑾。 DB52/T 1541.42021 1 政务数据平台 第 4 部分：接口规范 1 范围 本文件规定了政务数据平台数据接口的术语和定义、缩略语、基本要求、接口组成、接口要求和接口安全。 本文件适用于政务数据平台接口的设计和应用。 2 规范性引用文件 本文件没有规范性引用文件。 3 术语和定义 下列术语和定义适用于本文件。 3.1 接口 interface 基于应用程序的服务能力封装成接口，并通过API网关开放给客户端调用。 3.2 数据 data 对事实、概念或指令的一种形式化表示，适用于以人工或自动方式进行通信、
5、解释或处理。 来源：DB52/T 1239.1-2017，3.1 3.3 政务数据资源目录 directory of government data resources 通过对政务数据资源依据规范的元数据描述，按照一定的分类方法进行排序和编码的一组信息,用以描述各个政务数据资源的特征，以便于对政务数据资源的检索、定位与获取。 3.4 政务数据提供方 government data provider 基于统一数据共享交换平台，利用各种技术向其他政务部门、事业单位、企业或公众提供政务数据的实体。 DB52/T 1541.4202123.5访问令牌access token访问控制操作主体的系统对象。
6、4缩略语下列缩略语适用于本文件。API：应用程序编程接口（Application Programming Interface）HTTP：超文本传输协议（Hyper Text Transfer Protocol）HTTPS：超文本传输安全协议（Hyper Text Transfer Protocol over SecureSocket Layer）JSON：轻量级的数据交换格式（Javascript Object Notation）REST：一种网络应用程序的设计风格和开发方式（Repersentational State Transfer）5基本要求5.1应采用 HTTP/HTTPS 作为传输
7、协议。5.2应采用 JSON 作为消息的封装格式。5.3应提供服务请求成功、失败等各种情况的接口返回状态码。5.4应支持跨语言、跨操作系统调用。6接口组成政务数据平台接口主要包括：认证授权服务接口、组织接口、用户接口、数据资源目录接口。政务数据平台接口组成见图1。图 1政务数据平台接口组成图DB52/T 1541.4202137接口要求7.1认证授权服务接口接口描述： 政务数据提供方接入政务数据平台应调用认证授权服务接口。 通过平台认证授权服务接口进行身份验证， 验证成功后接口返回的授权访问令牌， 政务数据提供方操作政务数据平台接口应携带访问令牌，进行正常会话交互。接口地址：/api/auth
8、_service。接口类型：post。请求参数：认证授权服务接口请求参数见表1。请求示例：见附录A。返回参数：见附录I 表I.1。返回示例：见附录H。表 1认证授权服务接口请求参数表参数名称类型是否必填说明access_keystring是政务数据平台分配给政务数据提供方的唯一标识access_secretstring是政务数据平台分配给政务数据提供方的密钥usernamestring是政务数据平台分配给政务数提供方的用户账户名称passwordstring是政务数据平台分配给政务数据提供方的用户账户密码7.2组织接口7.2.1组织新增接口接口描述：政务数据提供方调用政务数据平台组织新增接口，
9、获取政务数据平台返回的组织ID，根据组织ID进行政务数据提供方系统和政务数据平台交互。接口地址：/api/add/organization。接口类型：post。请求参数：同步组织机构请求参数见表2。请求示例：见附录B。返回参数：见附录I 表I.1。返回示例：见附录H。表 2同步组织机构请求参数表参数名称类型是否必填说明addTypeint是操作类型：1 表示新增trustNoint是统一社会信用代码groupShortNamestring是组织简称groupNamestring是组织名称regionNamestring是组织所属地区orgPostNoint是组织区划编号group_leveli
10、nt是级别：401 省直，402 市州super_orgint是父级组织编号DB52/T 1541.4202147.2.2组织编辑接口接口描述：编辑组织机构信息。接口地址：/api/add/organization。接口类型：post。请求参数：组织机构编辑请求参数见表3。请求示例：见附录B。返回参数：见附录I 表I.1。返回示例：见附录H。表 3组织机构编辑请求参数表参数名称类型是否必填说明addTypeint是操作类型：2 表示编辑trustNoint是统一社会信用代码groupShortNamestring是组织简称groupNamestring是组织名称regionNamestring
11、是组织所属地区orgPostNoint是组织区划编号group_levelint是级别：401 省直，402 市州super_orgint是父级组织编号7.2.3组织查询接口接口描述：政务数据提供方查询政务组织机构信息。接口地址：/api/organization/query。接口类型：get。请求参数：组织机构查询接口请求参数见表4。请求示例：http:/ip+port/api/organization/query?org_name=组织名称&org_id=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。返回参数：见附录I 表I.1。返回示例：见附录H。表 4组织机构查询接
12、口请求参数表参数名称类型是否必填说明org_idstring是组织 idorg_namestring是组织名称7.3用户接口7.3.1用户新增接口接口描述：政务数据提供方调用用户新增接口，同步组织机构用户信息到政务数据平台。接口地址：/api/add/user。接口类型：post。请求参数：组织机构用户新增请求参数见表5。DB52/T 1541.420215请求示例：见附录C。返回参数：见附录I 表I.1。返回示例：见附录H。表 5组织机构用户新增请求参数表参数名称类型是否必填说明org_idstring是组织 idaddTypeint是操作类型：1 表示新增userNamestring是用户
13、名trueNamestring是用户真实姓名roIdsstring否用户角色mobilestring是联系电话7.3.2用户编辑接口接口描述：政务数据提供方编辑政务组织机构用户信息。接口地址：/api/add/user。接口类型：post。请求参数：组织机构用户编辑请求参数见表6。请求示例：见附录C。返回参数：见附录I 表I.1。返回示例：见附录H。表 6组织机构用户编辑请求参数表参数名称类型是否必填说明org_idstring是组织 idaddTypeint是操作类型：1 表示新增userNamestring是用户名trueNamestring是用户真实姓名roIdsstring是用户角色7
14、.3.3用户查询接口接口描述：政务数据提供方查询政务数据平台组织机构用户信息。接口地址：/api/query/user。接口类型：get。请求参数：用户查询见请求参数表7。请求示例：http:/ip+port/api/user/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。返回参数：见附录I 表I.1。返回示例：见附录H。表 7用户查询请求参数表参数名称类型是否必填说明userIdstring是用户 idDB52/T 1541.4202167.4数据资源目录接口7.4.1数据资源目录新增接口接口描述：政务数据提供方同步政务组织机构的数据资源目录信息
15、到政务数据平台。接口地址：/api/add/resource。接口类型：post请求参数：数据资源目录新增请求参数见表8。请求示例：见附录D。返回参数：见附录I 表I.1。返回示例：见附录H。表 8数据资源目录新增请求参数表参数名称类型是否必填说明idstring是数据资源目录 idindustryIdstring是行业 idorgIdstring是组织 idtopicIdstring是主题 iduserIdstring是用户 idaddTypeint是操作类型：1 表示新增apiDatajsonObject是接口信息描述见图 2，数据结构见附录 D、附录 EdirectoryjsonObje
16、ct是目录信息描述见图 3数据结构见附录 F、附录 Gindustrystring是行业openAttributeint是开放属性：1 有条件开放；2无条件开放；3不予开放serviceNamestring是服务名称shareAttributeint是共享属性：1有条件共享；2无条件共享；3不予共享topicstring是主题uniscidstring是统一社会信用代码DB52/T 1541.420217图 2接口信息描述组成结构图一町提到一一，翻_. 甜尴l曲阜-F叫时-剑.r圃票制.咀品ffl，.一一1一一.畸罔幅脑H血叫町.岛，-凰J町帽帽._.111喃喃阴晴电mg，制剧自-川P，u.睛
17、-hA.幢置.，F岳属w幅.-嗣一DB52/T 1541.420218图 3目录信息描述组成结构图7.4.2数据资源目录编辑接口接口描述：政务数据提供方编辑数据资源目录信息。接口地址：/api/add/resource。接口类型：post。请求参数：数据资源目录编辑请求参数见表9。请求示例：见附录D。返回参数：见附录I 表I.1。返回示例：见附录H。表 9数据资源目录编辑请求参数表参数名称类型是否必填说明idstring是数据资源目录 iduserIdstring是用户 idaddTypeint是操作类型：2 表示编辑openAttributeint是开放属性：1有条件开放；2无条件开放；3不
18、予开放shareAttributeint是共享属性：1有条件共享；2无条件共享；3 不予共享7.4.3数据资源目录查询接口接口描述：政务数据提供方查询数据资源目录信息。接口地址：/api/resource/query。接口类型：post。请求参数：数据资源目录查询请求参数见表10。请求示例：http:/ip+port/api/resource/query?userId=z6lqTzG3PTPpQIE92Bs0pA3PSyVJmlWM。DB52/T 1541.420219返回参数：见附录I 表I.1。返回示例：见附录H。表 10数据资源目录查询请求参数表参数名称类型是否必填说明idstring是
19、数据资源目录 iduserIdstring是用户 id8接口安全8.1对请求的合法性进行校验。8.2对请求的数据进行校验。8.3对请求实现黑明单与白名单拦截。8.4对请求实现用户使用接口的流量限制。DB52/T 1541.4202110AA附录A（资料性）认证授权服务接口 JSON Schema 示例下面给出认证授权服务接口JSON Schema示例。示例：$schema: http:/json-schema.org/draft-07/schema,$id: http:/ object,title: The root schema,examples: app_key: C3kFcJP5Pw5w
20、13nBX2GCh03zSrn8p7BA,app_secret: rmnnkSkWfx0A7w6n13bKrwPGaM0dEQr6,username: test,password: 8vJDXhG2waQ5rAxG,required: app_key,app_secret,username,passwordDB52/T 1541.4202111BB附录B（资料性）组织新增接口 JSON Schema 示例下面给出组织新增接口JSON Schema示例。示例：$schema: http:/json-schema.org/draft-07/schema,$id: http:/ object,tit
21、le: The root schema,description: The 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
22、,groupName,regionName,orgPostNo,group_level,super_orgDB52/T 1541.4202112CC附录C（资料性）用户新增接口 JSON Schema 示例下面给出用户新增接口JSON Schema示例。示例：$schema: http:/json-schema.org/draft-07/schema,$id: http:/ object,title: The root schema,description: The root schema comprises the entire JSON document.,examples: addTyp
23、e: 1,userName: example,trueName: 示例,roIds: sdfsdf,org_id: ssKXRauteJN0V93krd,mobile: KXRay9teJN0V93kvgk,required: addType,userName,trueName,roIds,org_id,mobileDB52/T 1541.4202113DD附录D（资料性）数据资源目录接口的接口信息 JSON Schema 示例数据资源目录接口的接口信息JSON Schema示例。示例：$schema: http:/json-schema.org/draft-07/schema,$id: ht
24、tp:/ object,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,
25、createTime: 1590647639923,description: 描述,requestDemo: ?pageIndex=1&pageSize=50,requestMode: 1,requestParam: description: 分页，当前页,must: 0,name: pageIndex,type: 1,responseDemo: ,responseParam: description: 号码,DB52/T 1541.4202114name: id,type: 2,responseType: 1,resultCode: description: 成功,name: 200,upd
26、ateTime: 1590647639923,url: http:/ip+port/,required: bodyType,createTime,description,requestDemo,requestMode,requestParam,responseDemo,responseParam,responseType,resultCode,updateTime,urlDB52/T 1541.4202115EE附录E（资料性）数据资源目录接口信息描述对象参数表数据资源目录接口信息描述对象参数表见表E.1。表 E.1数据资源目录接口信息描述对象参数表参数名称类型是否必填说明bodyTypein
27、teger是接口类型createTimeinteger是创建时间descriptionstring是用途描述requestDemostring是服务调用示例requestModeinteger是请求方法requestParamarray是请求参数responseDemostring是响应示例responseParamarray是响应参数responseTypeinteger是响应类型resultCodearray是状态码说明updateTimeinteger是更新时间urlstring是接口服务地址DB52/T 1541.4202116FF附录F（资料性）数据资源目录接口的目录信息 JSON
28、Schema 描述示例下面给出数据资源目录接口的目录信息JSON Schema描述示例。示例：$schema:http:/json-schema.org/draft-07/schema,$id:http:/ root schema,description:The root schema comprises the entire JSON document.,required:directory,properties:directory:$id:#/properties/directory,type:object,title:The directory schema,description:An
29、 explanation about the purpose of this instance.,default:,examples:infoItems:description:身份证号码,length:100,name:id,type:varchar,serviceName:饮水安全,system:system:回归测试,systemId:710b8d8c-e868-4b55-9e4d-d2b50ad78521,DB52/T 1541.4202117required:infoItems,serviceName,systemDB52/T 1541.4202118GG附录G（资料性）数据资源目录
30、描述对象参数表数据资源接口描述对象参数表见表G.1。表 G.1数据资源目录描述对象参数表参数名称类型是否必填说明infoItemsarray是信息项serviceNamestring是服务名称systemobject是系统名称DB52/T 1541.4202119HH附录H（资料性）政务数据平台接口返回 JSON Schema 示例下面给出政务数据平台接口返回JSON Schema示例。示例：$schema: http:/json-schema.org/draft-07/schema,$id: http:/ object,title: The root schema,examples: sta
31、tus: 成功返回状态码值或失败返回状态码值,message: 成功时状态码说明或失败时状态码值说明,required: status,message,properties: status: $id: #/properties/status,type: string,title: The status schema,description: An explanation about the purpose of this instance.,default: ,examples: 成功返回状态码值或失败返回状态码值,message: $id: #/properties/message,type
32、: string,title: The message schema,description: An explanation about the purpose of this instance.,default: ,examples: 成功时状态码说明或失败时状态码值说明DB52/T 1541.4202120,additionalProperties: trueDB52/T 1541.4202121II附录I（资料性）政务数据平台接口返回参数表政务数据平台接口返回参数表见表I.1。表 I.1政务数据平台接口返回参数表参数名称类型是否必填说明statusinteger是成功返回状态码值或失败返回状态码值messageString是成功时状态码说明或失败时状态码值说明_ DB52/T 1541.4-2021
