DB4401∕T 81-2020 广州“数字教育城”接口技术规范

ICS35.240.01

L67

正DB4401

广州市地方标准

DB4401/T81—2020

代替DBJ440100/T287—2017

广州“数字教育城”接口技术规范

Interfacetechnicalspecificationsfor

Guangzhou“Digitaleducationcity”

2020-06-08发布2020-07-01实施

广州市市场监督管理局发布

DB4401/T81－2020

前言

本标准按照GB/T1.1—2009给出的规则起草。

本标准由DBJ440100/T287—2017《广州“数字教育城”接口技术规范》确认转化而来，并代替

DBJ440100/T287—2017《广州“数字教育城”接口技术规范》。

本标准与DBJ440100/T287—2017相比，除编辑性修改外，主要技术变化如下：

——“术语和定义”增加各术语对应英文；

——修改了起草单位名称。

本标准由广州市教育局提出并归口。

本标准起草单位：广州市教育信息中心（广州市电化教育馆）。

本标准主要起草人：罗胜涛、秦小珊、余智德、袁方正。

DBJ440100/T287—2017于2017年8月31日首次发布。

I

DB4401/T81－2020

广州“数字教育城”接口技术规范

1范围

本标准规定了广州“数字教育城”接口的术语和定义、接口机制、登录接口技术规范、接口数

据规范以及数据服务接口规范。

本标准适用于广州“数字教育城”信息系统接口的规划、设计与实施，将分散、异构的应用进

行整合，通过统一的访问入口，实现各种应用系统与广州“数字教育城”的无缝接入和集成，用于

指导软件开发者对接入广州“数字教育城”的系统进行单点登录整合、用户账户数据同步及基础数

据获取。

2术语和定义

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

2.1

数字教育城digitaleducationcity

以“一网一平台、两库四中心”（一网：广州教育科研网，一平台：广州“数字教育城”公共服

务平台；两库：基础教育管理数据库、基础教育教学资源库；四中心：学生学习发展中心、社区学

习交流中心、教育电子政务中心、教师学习发展中心）为主体内容，以全市中小学（含中等职业学

校）教师和学生为服务对象的教育信息化基础性平台。其主要服务覆盖教学与研究、学习与培训、

活动与交流、资源与工具、班级空间、个人网页等方面，支持信息技术与教育教学的深度融合。

2.2

凭证ticket

用户在通过单点登录验证后获得的信息，包含用户的基本信息，如唯一标识、登录名、有效期

等，以Ticket表示。

2.3

凭证标识ticketidentifier

用户在通过单点登录验证后获得凭证的唯一标识。

2.4DB4401

单点登录singlesignon

是多个信息系统整合的技术手段，用户只需要登录一次就可以访问所有相互信任的应用系统。

2.5

伪单点登录pseudosinglesignon

用户访问一个应用首次登录时，伪单点系统提示输入用户名和密码，并保存到数据库中，同时

将用户名和密码填充到动态表单并提交。当用户再次访问该邮件系统时，伪单点登录系统将自动提

交表单，实现单点登录，从而实现自动登录。

2.6

分发distribution

数据生产者通过各种方式将数据传送到消费者的过程。

3接口机制

1

DB4401/T81－2020

3.1单点登录

用户第一次访问应用系统，会被引导到认证系统中；根据用户提供的登录信息，认证系统进行

身份校验，通过校验，返回给用户一个认证的凭据；用户带上凭据，作为认证的凭据，应用系统接

受到请求后会把凭据送到认证系统进行校验，检查合法则通过校验，完成登录。

3.2伪单点登录

首次访问时，伪单点系统会提示输入该应用系统的用户名、密码、编码方式、表单提交方式等

信息，并保存到数据库中。当用户再次使用该系统时，伪单点登录系统将从系统提取用户上次保存

的信息并自动提交表单，实现自动登录。

3.3数据同步

源用户基础信息有时间戳字段，记录数据被修改的时间，同时各子系统也存在有用户基础信息

的备份，该备份也有一个时间戳。当用户用单点登录技术登录到子系统时，该用户的基础信息以及

时间戳会以XML的形式捎带到子系统，子系统只需检查捎带过来的时间戳与备份是否一致，如果不

一致，则以源系统为准进行修改。

4登录接口技术规范

4.1单点登录技术规范

4.1.1具体机制如图1所示。

应用系统1

1登录信息

用户认证系统

2ticket

3ticket4ticket验证

应用系统2

5ticket用户信息

6ticket验证

应用系统3

图1单点登录机制

4.1.2当用户第一次访问应用系统1时，会被引导到认证系统中进行登录；根据用户提供的登录信

息，认证系统进行身份校验，如通过校验，应返回给用户一个认证的凭据（ticket）；用户再访问其

他应用时，将这个ticket带上，作为认证的凭据，应用系统接受到请求后将把ticket送到认证系

统进行校验，检查ticket的合法性。如果通过校验，用户可在不用再次登录的情况下访问应用系统

2和应用系统3。

4.1.3PHP系统单点登录示例参见附录A，JAVA系统单点登录示例参见附录B，C#系统单点登录规

2

DB4401/T81－2020

范示例参见附录C。

4.2伪单点登录技术规范

4.2.1创建动态表单，提交用户预先录入的用户名和密码等信息，完成自动登录过程。具体流程如

图2所示。

4.2.2当用户访问一个应用，首次访问时，伪单点系统会提示输入该应用系统的用户名、密码、编

码方式、表单提交方式等信息，并保存到数据库中，同时将用户名和密码填充到动态表单，创建动

态表单自动提交，从而实现自动登录。当用户再次使用该系统时，伪单点登录系统将从系统提取用

户上次保存的信息并自动提交表单，实现自动登录，不需再手工输入登录所需信息。业务子系统如

果需要以伪单点登录形式接入教育城，用户登录的页面不能含有验证码，或者单独提供一个不带验

证码的登录页面，表单提交方式应为get或post方式。

用户点击需伪单点

的系统

已设定了用户名

和密码

是

否

保存用户名、密码、目

标系统url、编码、表单

提交方式等信息

新建窗口

用javascript创建表单

GetorPost?

以get方式提交以post方式提交

结束

图2伪单点登录流程DB4401

4.3基于捎带的时间戳同步规范

4.3.1为了保持接入”数字教育城”各子系统的用户基础数据与源的一致性，可采用基于捎带的时

间戳同步技术，具体流程如图3所示。

3

DB4401/T81－2020

用户单点登录到

子系统

检查源系统与目标

是

系统的时间戳是否

一致？

否

更新目标系统的信息，并

将该条记录的时间戳设

为源记录的时间戳

结束

图3基于时间戳的同步方法

4.3.2首先在源用户基础信息增加一个时间戳字段，记录数据被修改的时间，同时各子系统也存在

有用户基础信息的备份，该备份也有一个时间戳。当用户用单点登录技术登录到子系统时，该用户

的基础信息以及时间戳会以XML的形式捎带到子系统，子系统只需检查捎带过来的时间戳与备份是

否一致，如果不一致，则以源系统为准进行修改。

5接口数据规范

5.1教师用户数据规范

教师用户数据参数如下：

a）userPersonId：身份证号；

b）givenName：用户真实姓名；

c）schooId：学校ID；

d）schoolName：学校名称；

e）userType：用户类型（teacher--教师）；

f）teacherCourse：教师授课课程，一般格式为[{"classId":0,"className":"二班

","gradeId":0,"gradeName":"初二","subjectId":0,"subjectName":"物理"}]；

g）birthday：用户出生日期；

h）sex：性别；

i）userName：系统标识的用户名；

j）phoneNumber：电话号码；

k）email：电子邮箱；

l）zone：学校所在的行政区。

4

DB4401/T81－2020

5.2学生用户数据规范

学生用户数据参数如下：

a）givenName：用户真实姓名；

b）schoolId：学校ID；

c）schoolName：学校名称；

d）gradeId：年级ID；

e）gradeName：年级名称；

f）classId：班级ID；

g）className：班级名称；

h）userType：用户类型（student--学生）；

i）birthday：用户出生日期；

j）sex：性别；

k）userPersonId：身份证号；

l）studentNumber：学号；

m）userName：系统标识的用户名；

n）phoneNumber：电话号码；

o）email：电子邮箱；

p）zone：学校所在的行政区。

5.3行政人员用户数据规范

行政人员用户数据参数如下：

a）givenName：用户真实姓名；

b）userPersonId：身份证号；

c）schoolId：学校ID；

d）schoolName：学校名称；

e）userType：用户类型（manager--行政人员）；

f）birthday：用户出生日期；

g）sex：性别；

h）userName：系统标识的用户名；

i）phoneNumber：电话号码；

j）email：电子邮箱；

k）zone：学校所在的行政区。DB4401

6数据服务接口规范

6.1获取批量用户信息接口

获取批量用户信息接口见表1。

表1

项目方法描述

接口名称getBatchUserInfo

接口说明使用者可根据此方法，批量获取用户的属性信息

5

DB4401/T81－2020

表1（续）

项目方法描述

请求方式HTTPGET

http格式的String字符串：

接口格式/getBatchUserInfo.jspx?pIndex=1&pageSize=30

&userType=teacher&schoolId=440113004261

1）pIndex:页码，int类型，必填

2）pageSize:一页记录数，int类型，必填

输入参数3）userType：批量获取用户类型，默认不传值--所有用户类型、student--学生、teacher--教师、

manager--行政人员，String类型，可选

4）schoolId：学校ID，String类型，必填

JSON字符串，参见附录D。

注意：

1）查询出来的结果值为null的表示该字段没有信息；

2）接口调用者可以通过result来判断该查询是否成功，false表示查询失败，true表示查询成功，但

返回值

是查询成功并不代表有记录数，只是单纯表示此次查询操作没有异常，如果要判断是否有记录可读则需

检查RowCount字段；

3）任何小于等于页数1的页数索引默认返回第一页，任何大于等于总页数的页数索引默认返回最后一

页。

1）页码格式错误，比如传入字符或者不传

{result:”false”,info:“页码格式不对，请输入正整数！”}

异常

2）每页记录数格式错误，比如传入字符或者不传

{result:”false”,info:”每页的记录数格式不对，请输入正整数！”}

功能提供给第三方批量获取用户信息

一个教师可以同时教授不同班级或科目，因此返回的teacherCourse有可能是个数组；如果教师还没有

备注

完善该字段，则teacherCourse字段为null。

6.2获取单个用户信息接口

获取单个用户信息接口方法见表2。

表2

项目方法描述

接口名称getUserInfo

接口说明本接口可以根据用户名获取单个用户的信息

请求方式HTTPGET

接口格式http格式的String字符串，例如：

/getUserInfo.jspx?userName=zhangsan

输入参数1）userName：用户名，String类型，必填

6

DB4401/T81－2020

表2（续）

项目方法描述

返回值JSON字符串，参见附录E。

注意：

1）查询出来的结果值为null的表示该字段没有信息；

2）接口调用者可以通过result来判断该查询的结果是否有记录，true表示查询有结果，false表示查

询没有结果，即记录数为0。

异常一般情况下该接口没有异常返回，如果找不到查询的记录，字段result将被设置为false并且返回如

下json字符串：

{"result":"false","data":{}}

功能提供给第三方，根据用户名获取一个用户的信息

备注一个教师可以同时教授不同班级或科目，因此返回的teacherCourse有可能是个数组；如果教师还没有

完善该字段，则teacherCourse字段为null

DB4401

7

DB4401/T81－2020

附录A

(资料性附录)

PHP系统单点登录示例

A.1首先找到PHP网站的总入口文件，一般是index.php，或者程序执行必经的其他文件，在里面

适当位置添加登录处理代码；

A.2引入caslogin()，验证成功后通过getUser函数可以获取登录用户基础数据，如下：

$phpcas_path=SITE_PATH."/CAS-1.3.2";//PHPCAS客户端路径

$cas_host="";//填写cas服务器部署的url或者ip

$cas_port=443;//cas访问的端口

$cas_context="cas";

require_once$phpcas_path.'/CAS.php';

phpCAS::client(CAS_VERSION_2_0,$cas_host,$cas_port,$cas_context);

phpCAS::setNoCasServerValidation();//使用非SSL验证

//phpCAS::setCasServerCACert("D:/zheng2.cer");//使用SSL验证

phpCAS::forceAuthentication();

$username=phpCAS::getUser();//获取登录后的用户名

A.3通过getAttribute函数获取登录用户的其他信息，如学校、班级，存到SESSION里面如下：

$_SESSION["userContent"]=array();

$_SESSION["userContent"]["userType"]=phpCAS::getAttribute("userType");

$_SESSION["userContent"]["givenName"]=

urldecode(phpCAS::getAttribute("givenName"));

$_SESSION["userContent"]["email"]=urldecode(phpCAS::getAttribute("email"));

$_SESSION["userContent"]["schoolName"]=

urldecode(phpCAS::getAttribute("schoolName"));

$_SESSION["userContent"]["userName"]=phpCAS::getAttribute("userName");

//教师用户信息需要处理课程JSON格式转换

if($_SESSION["userContent"]["userType"]=="teacher"){

$course=urldecode(phpCAS::getAttribute("teacherCourse"));

$course=str_replace(""","\"",$course);

$_SESSION["userContent"]["teacherCourse"]=json_decode($course,true);

}

A.4时间戳同步

稍等的用户基础数据包含一个stamp字段，该字段为权威数据的时间戳，如果子系统的本地

stamp跟CAS的stamp不一致，说明用户数据有更新，子系统也应做相应的更新。

A.5单点退出

修改PHP项目登出代码，在登出代码引入caslogout()，如下：

$phpcas_path=SITE_PATH."/CAS-1.3.2";//PHPCAS客户端路径

$cas_host="";//填写cas服务器url或ip

$cas_port=443;//cas访问的端口

$cas_context="cas";

require_once$phpcas_path.'/CAS.php';

phpCAS::logoutWithRedirectService("46/sns");

8

DB4401/T81－2020

附录B

(资料性附录)

JAVA系统单点登录示例

B.1导入证书ssl.crt到jdk和jre。

导入到jre：（路径根据需要修改）

keytool-import-trustcacerts-aliascasserver-filessl.crt-keystore"C:\Program

Files\Java\jdk1.6.0_38\jre\lib\security\cacerts"-storepasschangeit

导入到jdk：

keytool-import-trustcacerts-aliascasserver-filessl.crt-keystore"C:\Program

Files\Java\jre6\lib\security\cacerts"-storepasschangeit

B.2在JAVA项目的WEB-INF\lib目录下加入CAS的客户端cas-client-core-3.2.1.jar;

B.3在JAVA项目web.xml文件加入以下filter;

<!--CAS客户端配置-->

<listener>

<listener-class>

org.jasig.cas.client.session.SingleSignOutHttpSessionListener

</listener-class>

</listener>

<!--该过滤器用于实现单点登出功能，可选配置。-->

<filter>

<filter-name>CASSingleSignOutFilter</filter-name>

<filter-class>

org.jasig.cas.client.session.SingleSignOutFilter

</filter-class>

</filter>

<filter-mapping>

<filter-name>CASSingleSignOutFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

<filter>

<filter-name>CASAuthenticationFilter</filter-name>

DB4401

<filter-class>

org.jasig.cas.client.authentication.AuthenticationFilter

</filter-class>

<!--CAS验证服务器地址，有域名填写域名-->

<init-param>

<param-name>casServerLoginUrl</param-name>

<param-value>

/cas/login

</param-value>

</init-param>

<init-param>

<param-name>renew</param-name>

9

DB4401/T81－2020

<param-value>false</param-value>

</init-param>

<init-param>

<param-name>gateway</param-name>

<param-value>false</param-value>

</init-param>

<!--客户端应用服务器地址,如果没有域名填写IP地址-->

<init-param>

<param-name>serverName</param-name>

<param-value>/</param-value>

</init-param>

</filter>

<!--负责Ticket校验-->

<filter>

<filter-name>CASValidationFilter</filter-name>

<filter-class>

org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter

</filter-class>

<init-param>

<param-name>casServerUrlPrefix</param-name>

<param-value>/cas/</param-value>

<!—注意:pengyin为CAS服务器的主机名-->

</init-param>

<init-param>

<param-name>serverName</param-name>

<param-value>/</param-value>

<!—注意:/为业务系统的地址-->

</init-param>

<init-param>

<param-name>useSession</param-name>

<param-value>true</param-value>

</init-param>

<init-param>

<param-name>redirectAfterValidation</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<filter>

<filter-name>CASHttpServletRequestWrapperFilter</filter-name>

<filter-class>

org.jasig.cas.client.util.HttpServletRequestWrapperFilter

</filter-class>

</filter>

10

DB4401/T81－2020

<filter>

<filter-name>CASAssertionThreadLocalFilter</filter-name>

<filter-class>

org.jasig.cas.client.util.AssertionThreadLocalFilter

</filter-class>

</filter>

<filter-mapping>

<filter-name>CASAuthenticationFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

<filter-mapping>

<filter-name>CASValidationFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

<filter-mapping>

<filter-name>CASHttpServletRequestWrapperFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

<filter-mapping>

<filter-name>CASAssertionThreadLocalFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

</web-app>

B.4修改JAVA项目登录验证代码；把原有登录的数据库用户名密码验证改为调

principal.getName()，从CAS服务器端获取用户名,并通过本项目数据库拿到User直接

session.setAttribute("user",user)登录;

@RequestMapping(value="/login.do",method=RequestMethod.GET)

publicStringlogin(HttpServletRequestrequest,HttpSessionsession,Mapmap){

AttributePrincipalprincipal=(AttributePrincipal)request.getUserPrincipal();

Mapattributes=principal.getAttributes();

Stringusername=principal.getName();

DB4401

/*其它可用参数

Stringemail=(String)attributes.get("email");

Stringdecodeemail=URLDecoder.decode(email,"UTF-8");

Stringgivename=(String)attributes.get("givenName");

Stringdecodename=URLDecoder.decode(givename,"UTF-8");

StringsystemRole=(String)attributes.get("userType");

Stringdecodeusertype=URLDecoder.decode(systemRole,"UTF-8");

Stringschoolname=(String)attributes.get("schoolName");

Stringdecodeschoolname=URLDecoder.decode(schoolname,"UTF-8");

Stringgradename=(String)attributes.get("gradeName");

Stringdecodegradename=URLDecoder.decode(gradename,"UTF-8");

Stringclassname=(String)attributes.get("className");

1111

DB4401/T81－2020

Stringdecodeclassname=URLDecoder.decode(classname,"UTF-8");

*/

Usersuser=usersDao.getUser(username);

session.setAttribute("user",user);

return"redirect:/bottle/show.do";

}

注：stamp，用户信息更新的时间戳，用于子应用系统与CAS系统的用户同步，如果子系统的stamp跟CAS的stamp

不一致，说明用户数据有更新。则子系统也应做相应的更新。

B.5修改JAVA项目登出代码

@RequestMapping(value="/logout.do",method=RequestMethod.POST)

publicStringlogout(HttpServletRequestrequest,HttpSessionsession,Mapmap){

session.removeAttribute("user");

return"redirect:/cas/logout";

12

DB4401/T81－2020

附录C

(资料性附录)

C#系统单点登录示例

C.1解压“统一身份认证平台单点登录C#接口部署包.rar”,修改iis的主目录，指向该目录。

C.2修改web.config，将loginUrl改为相应的cas登录验证地址。

<authenticationmode="Forms">

<formsloginUrl="/cas/login"timeout="30"defaultUrl="~/Thirdpart

y/GZEDU/Receive.aspx"cookieless="UseCookies"slidingExpiration="true"path="/GZEDUDem

o/"/>

</authentication>

C.3修改解压的目录中的login.aspx.cs文件，修改“privateconststringCASHOST=

"/cas/ss";”为对应的cas服务器地址。

//略去CAS登录判断，以下为CAS登录成功后，ticket验证部分，从ticket验证返回信息即

可获得用户信息

ServicePointManager.ServerCertificateValidationCallback=newSystem.Net.Security.

RemoteCertificateValidationCallback(CheckValidationResult);

stringvalidateurl=CASHOST+"serviceValidate?"+"ticket="+tkt+"&"+"servi

ce="+service;

StreamReaderReader=newStreamReader(newWebClient().OpenRead(validateurl));//

检验ticket是否有效

stringresp=Reader.ReadToEnd();

Session["user"]=getAttribute(resp,"user");//获取登录用户名

//以下根据返回信息构造用户信息，保存在session

Dictionary<string,string>userContent=newDictionary<string,string>();

userContent.Add("userType",getAttribute(resp,"userType"));

userContent.Add("givenName",getAttribute(resp,"givenName"));

userContent.Add("email",getAttribute(resp,"email"));

userContent.Add("schoolName",getAttribute(resp,"schoolName"));

userContent.Add("userName",getAttribute(resp,"userName"));

Session["userContent"]=userContent;

其中getAttribute定义如下：

DB4401

privatestringgetAttribute(stringresp,stringkey){

NameTablent=newNameTable();

XmlNamespaceManagernsmgr=newXmlNamespaceManager(nt);

XmlParserContextcontext=newXmlParserContext(null,nsmgr,null,XmlSpac

e.None);

XmlTextReaderreader=newXmlTextReader(resp,XmlNodeType.Element,contex

t);

stringvalue=null;

while(reader.Read())

{

stringtag=reader.LocalName;

1313

DB4401/T81－2020

if(tag==key){

value=reader.ReadString();

break;

}

}

reader.Close();

returnvalue;

}

注：stamp，用户信息更新的时间戳，用于子应用系统与CAS系统的用户同步，如果子系统的stamp跟CAS的stamp

不一致，说明用户数据有更新。则子系统也应做相应的更新。

C.4退出：修改logout.aspx.cs文件，修改“privateconststringCASHOST=

"/cas/

ss";”为对应的cas服务器地址，将“privateconststringSERVICE=

“:8888””改为对应的服务首页地址。

14

DB4401/T81－2020

附录D

(资料性附录)

获取批量用户信息接口返回值示例

获取批量用户信息接口返回值示例：

{

"RowCount"：944,

"PageCount：473,

"PageSize"：2，

"CurrentPage"：10,

"result"："true",

"data":[

{

"user":{

"teacherCourse":"null",

"birthday":"1997-01-01",

"stamp":"2013-07-1412:01:25.0",

"sex":"女",

"schoolName":"天河区中学",

"gradeId":"null",

"userPersonId":,

"classId":"null",

"studentNumber":"440183001125200310016",

"givenName":"张三",

"userType":"student",

"gradeName":"null",

"phoneNumber":,

"email":"12345678@",

"userName":"张三",

"className":"null",

"schoolId":"44011234567",

"zone":"天河区"

DB4401

}

}，

{

"user":{

"teacherCourse":"null",

"birthday":"1997-01-01",

"stamp":"2013-07-1412:01:25.0",

"sex":"男",

"schoolName":"天河区中学",

"gradeId":"null",

"userPersonId":,

"classId":"null",

1515

DB4401/T81－2020

"studentNumber":"440183001125200310020",

"givenName":"李四",

"userType":"student",

"gradeName":"null",

"ph