17组-政务一体化数据平台接口说明

1. 范围

本文件规定了政务一体化数据平台数据接口的术语和定义、缩略语、基本要求、接口组成、接口要求和接口安全。本文件适用于政务一体化数据平台接口的设计和应用。

2. 规范性引用文件

本文件没有规范性别用文件。

3. 术语和定义

下列术语和定义适用于本文件。

3.1 接口 Interface

基于Web应用程序的服务能力封装成接口，并通过API网关开放给客户端调用。

3.2 数据 Data

对事实、概念或指令的一种形式化表示，适用于以人工或自动方式进行通信、解释或处理。

3.3 政务数据资源目录 Directory of government data resources

通过对政务数据资源依据规范的元数据描述，按照一定的分类方法进行排序和编码的一组信息，用以描述各个政务数据资源的特征，以便于对政务数据资源的检索、定位与获取。

3.4 政务数据提供方 Government data provider

基于政务数据一体化平台，利用各种技术向其他政务部门、企业或公众提供政务数据的实体。

3.5 访问令牌 Access token

访问控制操作主体的系统对象。

4. 缩略语

下列缩略语适用于本文件。
API：应用程序编程接口（Application Programming Interface）HTTP：超文本传输协议（Hyper Text Transfer Protocol）
HTTPS：超文本传输安全协议（Hyper Text Transfer Protocol over SecureSocket Layer）
JSON：轻量级的数据交换格式（Javascript Object Notation）（Repersentational State Transfer）

5. 基本要求

5.1 应采用HTTP/HTTPS作为传输协议。

5.2 应采用JSON作为消息的封装格式。

5.3 应提供服务请求成功、失败等各种情况的接口返回状态码。

5.4 应支持跨语言、跨操作系统调用。

6. 接口组成

政务数据平台接口主要包括：授权服务接口、政务人员接口、用户接口、数据资源目录接口。政务数据平台接口组成见下图。

7. 接口要求

7.1 授权服务接口

接口描述：政务数据提供方接入政务数据平台应调用认证授权服务接口。通过平台认证授权服务接口进行身份验证，验证成功后接口返回的授权访问令牌，政务数据提供方操作政务数据平台接口应携带访问令牌，进行正常会话交互。
接口地址：/api/access_service。接口类型：post。
请求参数：

参数名称	类型	是否必填	说明
access_id	string	是	平台分配给政务数据提供方/用户的id
access_key	string	是	平台分配给政务数据提供方/用户的密钥
access_source	string	是	政务数据提供方/用户请求访问的权限
access_rank	int	是	平台分配给政务数据提供方/用户的服务优先级

请求示例(JSON Schema)：

{"$schema":"http://json-schema.org/draft-07/schema", "$id":"http://example.com/example.json", "type"："object","title"："The root schema"，"examples"：[{"access_id":"C3kFcJP5Pw5w13nBX2GCh03zSrn8p7BA","access_key":"rmnnkSkWfx0A7w6n13bKrwPGall0dEQr6", "access_source"："test","access_rank":"1"}]"required"：["access_id", "access_key", "access_source", "access_rank"]

}

返回参数：

参数名称	类型	是否必填	说明
status	string	是	成功返回状态码值或失败返回状态码值
message	string	是	成功时状态码说明或失败时状态码值说明

返回示例：

{"$schema":" http://json-schema.org/draft-07/schema ","$id":" http://example.com/example.json ","type":"object","title":"The root schema","examples":[{"status"："成功返回状态码值或失败返回状态码值"，"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":"string","title":"The message schema","description":"An explanation about the purpose of this instance.","default":"","examples":["成功时状态码说明或失败时状态码值说明"]}
},
"additionalProperties":true
}

7.2 政务人员接口

暂未说明

7.3 用户接口

暂未说明

7.4 资源目录接口

7.4.1 数据资源目录新增接口
　　接口描述：政务数据提供方同步政务部门的数据资源目录信息到政务一体化数据平台。
　　接口地址: /api/add/resource。
　　接口类型: post
　　请求参数：数据资源目录新增请求参数见下表。

参数名称	类型	是否必填	说明
id	string	是	数据资源目录id
orgId	string	是	组织id
topicId	string	是	主题id
outData	string	是	出版日期
addType	int	是	操作类型:1表示新增
apiData	json0bject	是	接口信息描述见后文
directory	json0bject	是	目录信息描述见后文
openAttribute	int	是	开放属性:1有条件开放;2无条件开放;3不予开放
serviceName	string	是	服务名称
shareAttribute	int	是	共享属性:1有条件共享;2无条件共享;3不予共享
topic	string	是	主题

7.4.2 数据资源目录编辑接口
　　接口描述：政务数据提供方编辑数据资源目录信息。
　　接口地址: /api/add/resource。
　　接口类型: post。
　　请求参数,请求示例,返回参数,返回示例：见后文/待补充.
数据资源目录编辑请求参数表

参数名称	类型	是否必填	说明
id	string	是	数据资源目录id
userId	string	是	用户id
addType	int	是	操作类型:2表示编辑
openAttribute	int	是	开放属性:1有条件开放;2无条件开放;3不予开放
shareAttribute	int	是	共享属性:1有条件共享;2无条件共享;3不予共享

7.4.3 数据资源目录查询接口
　　接口描述：政务数据提供方查询数据资源目录信息。
　　接口地址: /api/resource/query。
　　接口类型: post。
　　请求参数：数据资源目录查询请求参数见表10。
　　请求示例: 见后文/待补充.
数据资源目录查询请求参数表:

参数名称	类型	是否必填	说明
id	string	是	数据资源目录id
userId	string	是	用户id

7.5 数据资源目录接口的接口信息JSON Schema示例:

    {"$schema":" http://json-schema.org/draft-07/schema ","$id":" http://example.com/example.json ","type":"object","title":"The root schema","abstract":"The root schema comprises the entire JSON document.","required":["apiData"] ,"properties":{"apiData" :{"$id":"#/properties/apiData","type":"object","title":"The apiData schema","abstract":"An explanation about the purpose of this instance.","default":{},"examples":["bodyType":0,"createTime":1590647639923,"abstract":"摘要","requestMode":1,"requestParam":[{"abstract":"","must":0,"name":"pageIndex","type":1}],"responseParam":[{"abstract":"号码","name":"id","type":2}] ,"responseType":1,"resultCode":[{"abstract":"成功","name":"200"}] ,"updateTime":1590647639923,"url":"http://ip+port/"}],"required":["bodyType","createTime","abstract","requestMode","requestParam","responseParam","responseType","resultCode","updateTime","url"]}}

数据资源目录接口信息描述对象参数表

参数名称	类型	是否必填	说明
bodyType	integer	是	接口类型
createTime	integer	是	创建时间
abstract	string	是	摘要
requestMode	integer	是	请求方法
requestParam	array	是	请求参数
responseParam	array	是	响应参数
responseType	integer	是	响应类型
resultCode	array	是	状态码说明
updateTime	integer	是	更新时间
url	string	是	接口服务地址

8. 接口安全

8.1 对请求的合法性进行校验。

8.2 对请求的数据进行校验。

8.3 对请求实现黑明单与白名单拦截。

8. 接口安全

8.1 对请求的合法性进行校验。

8.2 对请求的数据进行校验。

8.3 对请求实现黑明单与白名单拦截。

8.4 对请求实现用户使用接口的流量限制。