top
关闭

开发者登录

数据交换规范

前言

当前缺乏教育管理信息系统的标准,造成了极大的数据冗余和资源浪费,难以实现资源共享与数据交换。而仅仅对数据进行标准化,并不能从根本上解决不同系统之间数据交换的问题。本规范依据我国教育管理信息系统之间互操作的解决方案——教育管理信息系统互操作框架(EMIF)建立。本规范是针对数据提供方和数据使用方所制定的技术规范,旨在建立数据交换的标准,使框架内的所有系统在进行数据层整合时,要实现这些规范,并严格按照规范进行数据交换。

 

第三方开发者注册

开发者通过慧教云开放平台注册账号,上传审核所需的材料后,平台管理员会审核资料,审核通过后即成为平台开发者。

 

数据服务申请

开发者申请数据服务前需先注册应用,审核通过后会获取系统分配的appID和appKey,这两个参数将作为鉴权依据在数据服务交互过程使用(在4.1获取访问凭证环节会用到)。

开发者使用账号登录开放平台,进入管理中心订阅自己所需的数据服务,可以根据过滤选项过滤不需要的数据。数据服务订阅申请通过管理员审核后会返回订阅服务编码(会在4.2中用到),开发者需妥善保存该编码。

目前提供了六种数据服务,就能通过API消费对应的报文。

 

代理程序开发

4.1 获取接口访问凭证

根据开放平台开放的getaccesstoken接口获取数据服务的访问token(需要注册应用时返回的appID和appKey)。

4.1.1 接口描述

开发者调用平台接口的第一步,访问令牌是开发者使用数据服务的凭证,通过访问令牌开发者可以使用自身权限下的数据服务

4.1.2 前置条件

4.1.3 请求说明

urlhttp://ip:port/apigateway/getaccesstoken
协议Post
格式Json
是否需要鉴权
请求数限制
接口方向第三方应用>开放平台


4.1.4 请求参数 

序号字段名约束类型长度说明
1appid必选String64应用ID
2timestamp必选String
时间戳
3keyinfo必选String

对APPID、APPKEY、Timestamp进行sha1-hamc运算,

加密串为APPID和APPKEY及Timestamp字符串相连,

以APPKEY为加密参数; 

Php使用的签名函数:hash_hmac,hash_algos参数值为“sha1”


4.1.5 
返回参数 

序号字段名约束类型长度说明
1retCode必选String10返回码
2retDesc必选String
返回码描述
3tokenInfo必选JSON
返回的token对象信息
3.1validtime必选String32返回token有效期
3.2platformCode可选String10所属平台编码
3.3appKey必选String32应用Key
3.4userId必选String32用户编码
3.5appId必选String32应用ID
3.6token必选String32访问令牌
3.7id必选String32应用主键


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 数据订阅

订阅数据请求地址:
http://datacenterapi.d.huijiaoyun.com/dataCenterApi/api/subscription

传参说明:

字段名数据类型说明
serviceCodeString服务码
tokenStringtoken
isTestint是否在测试环境测试(0:正式环境 1:测试环境)



4.2.2 
数据发布 

发布数据请求地址:
http://datacenterapi.d.huijiaoyun.com/dataCenterApi/api/publish

传参说明:

字段名数据类型说明
serviceCodeString服务码
messageListString需要发布的报文
isTestint是否在测试环境测试(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
},
"operatorType": 1,
"platCode": "eduYun"
}
]

4.2.3 错误响应

错误响应格式:

当用户发布或订阅数据出错时,数据交换平台会返回给用户一个text/xml 格式的消息体。

 

示例:

<Error>

<Code>illlegalFieldValue</Code>

<Message>非法的字段类型,长度,或值</Message>

<desc>null</desc>

<returnTime>2016-09-19 00:00:00</returnTime>

</Error>

 

字段名数据类型说明
CodeString错误码
MessageString错误码对应的解释
descSting错误详情
returnTimeDate返回时间



错误码表:

错误码错误描述
dataCenterServiceException数据交换系统后台异常
dataCenterAccessDeny服务码无效
wrongJsonFormMsg所发报文非JSON ARRAY格式
illlegalFieldValue非法的字段类型,长度,或值



建立数据同步日志 

对于数据的提供方和使用方,要为数据的发布和订阅分别建立数据同步日志,为用户对数据有效性和完整性检查提供方便。

数据日志主要是记录第三方用户在发布/订阅过程中,发布/订阅的总量,失败的总量,以及失败的原因

发布/订阅日志的数据标准如下:

 

属性类型长度描述
IDVARCHAR232唯一标识
服务码VARCHAR232审核通过后得到的服务码
单笔总条数NUMBER3单笔批次的总条数
更新时间TIMESTAMP20最近一次发布的时间
状态位NUMBER11:成功 2:失败
失败原因REASON1来自于调用数据交换API返回的XML信息