DB4401-T 223-2023 教育电子学习资源数据接口规范

ICS35.240.01CCSL67DB4401Specificationofdatainterfaceforeducationale-learningresourcesIDB4401/T223—2023前言 III V 12规范性引用文件 13术语和定义 14接口数据模型及数据分类代码 14.1接口数据模型 14.2数据分类代码 55数据接口要求 5.1接口访问流程 5.2接口协议 5.3公共参数 5.4接口调用过程 5.5对象模型 5.6接口API 附录A（资料性）sha1加密代码实现(Java) 22附录B（资料性）数据接口示例 23参考文献 27DB4401/T223—2023本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由广州市教育局提出并归口。本文件起草单位：广州市电化教育馆、广州市标准化研究院、广州市越秀区市场监督管理局。本文件主要起草人：钟毅、孙立杰、彭斌、霍迎辉、郑勇、罗杰明、肖劲峰。DB4401/T223—2023V引言教育电子资源作为教育信息化业务中独特元素，承载着各种教学业务信息数据。目前现行国家、行业或地方标准无针对所有教育资源元数据，尤其是职业教育与幼儿教育、校本资源、校外课程等内容制定的标准。由于信息化技术发展迅速，各种类型的教育电子资源数据内容不断增加，出现获取资源渠道多难查询的问题，为此需出台相关标准，为全市教育电子资源管理提供参考依据。通过制定教育电子资源数据接口标准，可以统筹教师、学生、学校、校外企业等各种教育资源，形成统一规范，促进资源的共享与流转，提高资源利用率，消除由于部分教育资源内容不统一而导致的混乱无序等问题隐患。同时，统一教育电子资源数据接口标准，形成区域共建共享的资源体系基础，可促使市级平台向上与国家级、省级平台，向下与各区区级平台互联互通。本文件通过教育电子资源描述的定义与教育电子资源数据交互标准，把各级各类教育单位的资源通过数据接口方式整合，实现新增与已有的异构资源互访。广州教育电子资源的各个供应商、学校、机构通过数据交互，实现广州市内教育资源数据的共建共享。DB4401/T223—20231教育电子学习资源数据接口规范本文件规定了教育电子学习资源数据接口的数据模型、数据分类代码和数据接口要求。本文件适用于为广州市行政区域内学前教育、普通中小学和中等职业学校构建的教育电子资源数据的交互与共享。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件,仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GB/T4880.1—2005语种名称代码第1部分：2字母代码GB/T7408—2005数据元和交换格式信息交换日期和时间表示法GB/T28825—2012信息技术学习、教育和培训学习对象分类代码JY/T0607—2017基础教育教学资源元数据信息模型中国图书馆图书分类法（第五版）3术语和定义下列术语和定义适用于本文件。3.1教育电子学习资源educationale-learningresources在教学过程中使用的多种格式的电子文件。3.2数据接口datainterface数据平台内或平台之间不同组成部分衔接通讯的约定。4接口数据模型及数据分类代码4.1接口数据模型接口数据模型依据JY/T0607—2017建立，如表1所示。2DB4401/T223—2023表1接口数据模型12“zh”“en”“fr-CA”3固山下》赏析”4“通过基础知识识。”5“气密性”6测试版”78该资源的主要使用出“学龄前儿童”9DB4401/T223—20233表1接口数据模型（续）“http://www.m/”DB4401/T223—20234表1接口数据模型（续）册“2020-06-16”格式分类代码引用“2500”DB4401/T223—20235表1接口数据模型（续）串该资源存储的计算“/1.ppt”该资源属于的分类8描述该资源与关联_description4.2数据分类代码4.2.1语种分类代码语种分类代码从《中国图书馆图书分类法（第五版）》和GB/T4880.1—2005选取，如表2所示。表2语种分类代码————4.2.2学习方式分类代码DB4401/T223—20236学习方式分类代码如表3所示。表3学习方式分类代码4.2.3用户类型分类代码用户类型分类代码如表4所示。表4用户类型分类代码4.2.4专题教育分类代码专题教育资源分类代码按照《中国图书馆图书分类法（第五版）》类目简表和JY/T0607—2017，结合基础教育资源实际编制而成，如表5所示。表5专题教育分类代码DB4401/T223—20237表5专题教育分类代码（续）4.2.5年级分类代码年级分类代码按照GB/T28825—2012中适用对象分类代码，如表6所示。表6年级分类代码DB4401/T223—202384.2.6学科分类代码学科分类代码按照GB/T28825—2012中学科分类代码，如表7所示。表7学科分类代码DB4401/T223—20239表7学科分类代码（续）4.2.7资源类型分类代码资源类型分类代码如表8所示。表8资源类型分类代码————————————DB4401/T223—2023表8资源类型分类代码（续）————————4.2.8格式分类代码格式分类代码按照GB/T28825—2012中媒体格式分类代码，如表9所示。表9格式分类代码UOF(UnifiedOfficeDocumentFormPDF(PortableDocumentUMD(UniversalMobileDocumHTML(HyperTextMarkupLanguaXML(ExtensibleMarkupLDB4401/T223—2023表9格式分类代码（续）WMA(WindowsMediaAudAIFF(AudioInterchangeFileFormVQF(transform-domainweightedInterleaveVectorQuantizatiASF(AdvancedStreamingFormMPEG(MovingPicturesExpertsGrAVI(AudioVideoInterleavRMVB(RealMediaVariabWMV(WindowsMediaVidASF(AdvancedSystemsFormDVD(DigitalVersatileDB4401/T223—2023表9格式分类代码（续）JPEG（JointPhotographicExpGIF(GraphicsInterchangeFPNG(PortableNetworkGraphicFEPS(EncapsulatedPostCGM(ComputerGraphicEXIF(ExchangeableImaDXF(DrawingExchangeFoEPG(ElectronicPrograGIF(GraphicsInterchangeF4.2.9关联类型分类代码关联类型分类代码如表10所示。DB4401/T223—2023表10关联类型分类代码释5数据接口要求5.1接口访问流程所有接口统一按照HTTPPOST方式传递JSON格式数据，发起方定义为客户端，提供服务的为服务端。每一次数据请求为独立请求，前后两次请求之间没有关联。5.2接口协议5.2.1接口按照REST风格设计，通过HTTP协议的GET方法或POST方法提交请求。5.2.2使用GET方法，请求参数通过URL查询参数（QueryParam）提供。5.2.3使用POST方法，请求公共参数通过URL查询参数（QueryParam）提供，接口专用参数通过请求正文（Body）、按照JSON格式封装提供。5.3公共参数5.3.1接口的请求和返回均包含规定的公共参数，如无特殊说明，所有接口方法都应包含以下请求公共参数以及返回公共参数。5.3.2请求公共参数如表11所示。表11请求公共参数是否否DB4401/T223—2023表11请求公共参数（续）否应用程序发出请求的客户端时间，大平台在接收到请求后，与当前服务端时间比较，如果在误差范围大于10min，将请否应用程序发出请求的唯一标识号，大平台如果在误差时间内5.3.3返回公共参数如表12所示。表12返回公共参数是否否否否否否5.3.4错误信息结构如表13所示，错误代码说明如表14所示。表13错误信息结构是是否DB4401/T223—2023表14错误代码说明检查程序是否正确提供了所有接口方法（除login外）应提供有效的检查程序是否正确提供了11100~产生此错误的原因是会话尚未得到授权或者已经超时或话表示当前程序不是合法的应试在发送请求前自行进行签a)运行应用程序的客户端时间与接口服务端b)运行应用程序的客户端与接口服务端之间a)因为程序错误导致在多次调用中产生了相c)请求被记录并重放，建议排查网络安全问12100~如出现错误代码,例如类型第三方应用程序未获得DB4401/T223—2023表14错误代码说明（续）会话未获得授权调用指当前会话上下文无权限执行所操作的对象超出当前可能用来判断是否存在此对象，建议调用14110~14210~创建对象时主键或具有创建对象时不允许空属创建对象时部分属性不14310~创建对象时遇到的其它更新对象时主键或具有更新对象时不允许空属更新对象时部分属性不14410~更新对象时遇到的其它14510~在删除对象时遇到的其DB4401/T223—2023表14错误代码说明（续）19000~示接口服务端或客户端程序出现不可预测的内建议应用程序间隔一段时间后再自动尝试重5.3.5Sign生成规则按照一定顺序规则拼接ppKey、timestamp、randomNum、appSecre后，再使用sha1加密算法，生成最后签名。额外参数如表15所示。表15额外参数是5.3.6字符串顺序规则字符串顺序规则：appSecret+randomNum+appKey+timestamp+appSecret。5.3.7sha1加密代码实现(Java)sha1加密代码实现(Java)见附录A。5.4接口调用过程5.4.1调用login创建安全会话获取access_token调用安全会话接口的login方法，以部门管理员账户创建会话获取访问令牌access_token，请求示例见附录B中B.1.1。5.4.2使用access_token调用接口API把access_token作为请求的公共参数来调用接口API，示例见附录B中B.1.2。5.4.3调用logout注销会话调用安全会话接口的logout方法，设置access_token为无效，示例见附录B中B.1.3。5.5对象模型DB4401/T223—20235.5.1UserInfo（用户信息类）如表16所示。表16UserInfo（用户信息类）是是否是是是否否是否是5.5.2ResourceInfo（资源信息类）如表17所示。表17ResourceInfo（资源信息类）是是否否否是否是是否否否是否是是是是是DB4401/T223—2023表17ResourceInfo（资源信息类续）否否否是是是是是是是章是节是否否否是是是否否是否否否8否5.6接口API5.6.1安全会话登录接口security/login.do方法名称：login。方法说明：通过用户名和密码进行身份验证，验证成功后创建一个会话。所有对数据和附件的管理操作都应在有效的会话内进行。请求方法：POST。URL地址：http://{API_ROOT}/security/login.do。访问权限：所有通过授权的第三方程序。请求参数：请求参数如表18所示。DB4401/T223—2023表18请求参数是是是是否返回结果如表19所示。表19返回结果是是），否否是请求示例见附录B中B.2.1。返回示例见附录B中B.2.2。5.6.2安全会话注销接口security/logout.do方法名称：logout。方法说明：注销当前会话。请求方法：POST。URL地址：http://{API_ROOT}/security/logout.do。访问权限：所有已登录用户。请求参数：无。返回结果：无。请求示例见附录B中B.2.3。返回示例见附录B中B.2.4。5.6.3安全会话获取接口security/get_current_user.do方法名称：get_current_user。方法说明：获取当前已登录用户的信息。请求方法：GET。URL地址：http://{API_ROOT}/security/get_current_user。访问权限：所有已登录用户。请求参数：无。返回结果如表20所示。DB4401/T223—2023表20返回结果是否否请求示例见附录B中B.2.5。返回示例见附录B中B.2.6。5.6.4信息资源接口data_subject/list.do方法名称：list。方法说明：根据设置条件（支持标题、作者、用户类型等）查询数据主题信息。如：查询标题包含“三角形”资源。请求方法：POST。URL地址：http://{API_ROOT}/data_subject/list。访问权限：所有已登录用户。请求参数如表21所示。表21请求参数否否否返回结果如表22所示。表22返回结果否否请求示例见附录B中B.2.7。返回示例见附录B中B.2.8。DB4401/T223—2023（资料性）sha1加密代码实现（Java）importjava.nio.charset.StandardCharsets;importjava.security.MessageDigest;publicclassDigestSha{publicstaticvoidmain(String[]args){//使用方法StringappSecret="1";StringrandomNum="2";StringappKey="3";Stringtimestamp="4";DigestShaa=newDigestSha();Stringsign=a.sha1(appSecret+randomNum+appKey+timestamp+appSecret);System.out.println(sign);}publicStringsha1(Stringdata){MessageDigestmessageDigest;try{byte[]dataByte=data.getBytes(StandardCharsets.UTF_8);messageDigest=MessageDigest.getInstance("SHA-1");messageDigest.update(dataByte);byte[]finalDataByte=messageDigest.digest();char[]toDigits={'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'};finalintlen=finalDataByte.length;finalchar[]out=newchar[len<<1];for(inti=0,j=0;i<len;i++){//高位out[j++]=toDigits[(0xF0&finalDataByte[i])>>>4];//低位out[j++]=toDigits[0x0F&finalDataByte[i]];}returnnewString(out);}catch(Exceptione){thrownewRuntimeException(e);}}}DB4401/T223—2023数据接口示例B.1接口调用过程示例B.1.1下面给出了调用login创建安全会话登录获取access_token的示例。POSThttp://{API_ROOT}/securitContent-Type:applic","obj":null,"attributes":{"access_B.1.2下面给出了使用access_token调用接口API的示例。GEThttp://{API_ROOT}/security/get_current_user.do?access_to{,"data":{}}DB4401/T223—2023B.1.3下面给出了调用logout注销会话的示例。POSThttp://{API_ROOT}/secur