1 前言
当前缺乏教育管理信息系统的标准，造成了极大的数据冗余和资源浪费，难以实现资源共享与数据交换。而仅仅对数据进行标准化，并不能从根本上解决不同系统之间数据交换的问题。本规范依据我国教育管理信息系统之间互操作的解决方案——教育管理信息系统互操作框架（EMIF）建立。本规范是针对数据提供方和数据使用方所制定的技术规范，旨在建立数据交换的标准，使框架内的所有系统在进行数据层整合时，要实现这些规范，并严格按照规范进行数据交换。
2 第三方开发者注册
开发者通过慧教云开放平台注册账号，上传审核所需的材料后，平台管理员会审核资料，审核通过后即成为平台开发者。
3 数据服务申请
开发者申请数据服务前需先注册应用，审核通过后会获取系统分配的appID和appKey，这两个参数将作为鉴权依据在数据服务交互过程使用（在4.1获取访问凭证环节会用到）。
开发者使用账号登录开放平台，进入管理中心订阅自己所需的数据服务，可以根据过滤选项过滤不需要的数据。数据服务订阅申请通过管理员审核后会返回订阅服务编码（会在4.2中用到），开发者需妥善保存该编码。
目前提供了六种数据服务，就能通过API消费对应的报文。
4 代理程序开发
4.1 获取接口访问凭证
根据开放平台开放的getaccesstoken接口获取数据服务的访问token（需要注册应用时返回的appID和appKey）。
4.1.1 接口描述
开发者调用平台接口的第一步，访问令牌是开发者使用数据服务的凭证，通过访问令牌开发者可以使用自身权限下的数据服务。
4.1.2 前置条件
无
4.1.3 请求说明
| url | http://ip:port/apigateway/getaccesstoken |
| 协议 | Post |
| 格式 | Json |
| 是否需要鉴权 | 否 |
| 请求数限制 | 否 |
| 接口方向 | 第三方应用>开放平台 |
4.1.4 请求参数
| 序号 | 字段名 | 约束 | 类型 | 长度 | 说明 |
|---|---|---|---|---|---|
| 1 | appid | 必选 | String | 64 | 应用ID |
| 2 | timestamp | 必选 | String | 时间戳 | |
| 3 | keyinfo | 必选 | String | 对APPID、APPKEY、Timestamp进行sha1-hamc运算，加密串为APPID和APPKEY及Timestamp字符串相连,以APPKEY为加密参数; Php使用的签名函数：hash_hmac，hash_algos参数值为“sha1” |
4.1.5 返回参数
| 序号 | 字段名 | 约束 | 类型 | 长度 | 说明 |
|---|---|---|---|---|---|
|
1 |
retCode | 必选 | String | 10 | 返回码 |
| 2 | retDesc | 必选 | String | 返回码描述 | |
| 3 | tokenInfo | 必选 | JSON | 返回的token对象信息 | |
| 3.1 | validtime | 必选 | String | 32 | 返回token有效期 |
| 3.2 | platformCode | 可选 | String | 10 | 所属平台编码 |
| 3.3 | appKey | 必选 | String | 32 | 应用Key |
| 3.4 | userId | 必选 | String | 32 | 用户编码 |
| 3.5 | appId | 必选 | String | 32 | 应用ID |
| 3.6 | token | 必选 | String | 32 | 访问令牌 |
| 3.7 | id | 必选 | String | 32 | 应用主键 |
4.1.6 接口示例
|
请求参数： { "appid":"5736915E311EA64DEA******", "keyinfo":"E4AA972000C1262169743C******", "timestamp":"1458282******" }
返回值： { "tokenInfo": { "validtime": "14670914******", "platformCode": "", "appkey": "8583C30ED82CFC4169C4******", "userId": "AP93******", "appId": "B1901B73D882387798AA5******", "token": "77b117c4069e4f74b2434******", "id": "5736915E311EA64DEA49547******" }, "retCode": "000000", "retDesc": "获取Token成功。" } |
4.2 代理程序开发
开发者使用数据交换 RESTful API 即可进行数据的订阅和发布。
4.2.1 数据订阅
4.2.1.1 异步API调用
订阅数据请求地址：
http://datacenterapi.huijiaoyun.com/dataCenterApi/api/subscription
传参说明：
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| serviceCode | String | 服务码 |
| token | String | token值 |
| isTest | int | 是否在测试环境测试（0:正式环境 1:测试环境） |
4.2.1.2 同步URL推送方式
数据交换中心使用httpPost的方式，在需要时，将用户订阅的数据提交到各个应用或者子系统中。应用或者子系统只需要参考本规范实例程序，开发对数据交换中心提供 的标准表单处理程序即可。
状态码以及错误码
应用或者子系统返回数据交换中心的http状态码和提示信息，常见有以下一些
|
http status |
说明 |
|---|---|
| 200 | 服务器成功接收数据交换中心请求的数据 |
| 400 | 数据交换中心发出的请求数据有误 |
| 500 | 应用或者子系统内部错误 |
正常情况，返回结果为空，httpstatus设置为200；只有当状态码为400时，应用或者子系统才返回出错信息。例如
|
{
"timestamp": 1491444025030, "status": 400, "error": "INVALID REQUEST", "message": "用户发出的请求有错误，服务器没有进行新建或修改数据的操作。", "path": "/xxx" } |
url请求示例
|
post http://example.com/api/xxxxx
[ { "id":"157a5c1cad834cb7835379b38a1ab852", "isTest":0, "obj": { "areaCode":"420112", "cityCode":"420100", "orgaCage":"0", "orgaCode":"F6C68AAFA3BA437CE040007F01001D3D", "orgaId":"F6C68AAFA3B9437CE040007F01001D3D", "orgaName":"凌云小学", "orgaType":"3", "parentOrgaId":"F6C68AAFA38F437CE040007F01001D3D", "platCode":"888888", "provinceCode":"420000", "status":"0" }, "operatorType":1, "platCode":"888888" }, { "id":"157a5c1cad834cb7835379b38a1ab852", "isTest":0, "obj": { "areaCode":"420112", "cityCode":"420100", "orgaCage":"0", "orgaCode":"F6C68AAFA3BA437CE040007F01001D3D", "orgaId":"F6C68AAFA3B9437CE040007F01001D3D", "orgaName":"凌云小学", "orgaType":"3", "parentOrgaId":"F6C68AAFA38F437CE040007F01001D3D", "platCode":"888888", "provinceCode":"420000", "status":"0" }, "operatorType":1, "platCode":"888888" } ] |
具体报文的内容格式（obj）查看详细的报文说明文档
| 字段 | 内容 |
|---|---|
| id | 数据交换平台的主键id（后期比对数据） |
| isTest | 0- 正式的数据 1-测试数据 |
| obj | 交换报文的内容（机构数据，用户） |
| operatorType | 操作类型 1- 新增 2-修改 3-删除 |
| platCode | 来源编码 |
4.2.2 数据发布
发布数据请求地址：
http://datacenterapi.huijiaoyun.com/dataCenterApi/api/publish
传参说明：
| 字段名 | 数据类型 |
说明 |
|---|---|---|
| serviceCode | String | 服务码 |
| messageList | String | 需要发布的报文 |
| isTest | int | 是否在测试环境测试（0:正式环境 1:测试环境） |
messageList示例：
|
[
{ "obj": { "id": "F6C68AC1640C437CE040007F01001D3D", "classCode": "zlaryex7", "className": "五年级(1)班", "classType": "1", "foundTime": "2014-04-11", "grade": "3", "gradeClass": "1", "graduationTime": "2018", "orgaId": "d561316acd66458fa0a073c9d0d0a577", "status": "1", "studyPhase": "1", "platCode": "eduYun" }, "operatorType": "1"
} ] |
4.2.3 错误响应
错误响应格式：
当用户发布或订阅数据出错时，数据交换平台会返回给用户一个text/xml 格式的消息体。
示例：
|
<Error>
<Code>illlegalFieldValue</Code> <Message>非法的字段类型,长度,或值</Message> <desc>null</desc> <returnTime>2016-09-19 00:00:00</returnTime> </Error> |
| 字段名 | 数据类型 | 说明 |
|---|---|---|
| Code | String | 错误码 |
| Message | String | 错误码对应的解释 |
| desc | String | 错误详情 |
| returnTime | Date | 返回时间 |
错误码表：
| 错误码 | 错误描述 |
|---|---|
| dataCenterServiceException | 数据交换系统后台异常 |
| dataCenterAccessDeny | 服务码无效 |
| wrongJsonFormMsg | 所发报文非JSON ARRAY格式 |
| illlegalFieldValue | 非法的字段类型,长度,或值 |
5 建立数据同步日志
对于数据的提供方和使用方，要为数据的发布和订阅分别建立数据同步日志，为用户对数据有效性和完整性检查提供方便。
数据日志主要是记录第三方用户在发布/订阅过程中，发布/订阅的总量，失败的总量，以及失败的原因
发布／订阅日志的数据标准如下:
| 属性 | 类型 | 长度 | 描述 |
|---|---|---|---|
| ID号 | VARCHAR2 | 32 | 唯一标识 |
| 服务码 | VARCHAR2 | 32 | 审核通过后得到的服务码 |
| 单笔总条数 | NUMBER | 3 | 单笔批次的总条数 |
| 更新时间 | TIMESTAMP | 20 | 最近一次发布的时间 |
| 状态位 | NUMBER | 1 | 1:成功 2:失败 |
| 失败原因 | REASON | 1 | 来自于调用数据交换API返回的XML信息 |
鄂公网安备 42018502000485号