PDF《江西省教育资源公共服务平台》

附件: 江西省教育资源公共服务平台 开放 API 接口规范 (V1.

0) 江西省教育厅 二一七年九月 江西省教育资源公共服务平台开放 API 接口规范(V1.0) 目录前言.1 1. 范围.1 2. 术语、定义和缩略语.2 3. 开放平台技术架构.3 4. 第三方应用接入流程.5 4.1 线上接入申请流程.5 4.2 线下申请流程.7 4.3 API 使用规范.7 4.4 接入方式.8 5. 应用 API 调用流程.11 5.1 OAuth2.0 简介.11 5.2 获取 API 调用 Token.13 5.3 应用接口调用.14 5.3.1 公共参数.14 5.3.2 接口参数.14 5.3.3 示例.14 6. 统一身份认证.15 6.1 概述.15 江西省教育资源公共服务平台开放 API 接口规范(V1.0) 6.2 SSO 单点登录简介.15 6.3 Java 语言配置参考.19 6.4 php 语言配置参考.24 7. 第三方数据交换.28 7.1 第三方应用统计数据.28 7.2 第三方应用用户行为数据.28 7.3 第三方应用业务数据.29 8. 接口参考.29 8.1 基础数据服务.29 8.1.1 获取用户信息.29 8.1.2 获取班级信息.32 8.1.3 获取学校信息.36 8.1.4 获取区域信息.37 8.2 教育资源服务.41 8.2.1 资源元数据规范.41 8.2.2 数字教育资源服务接口.41 8.3 人人通空间服务.49 8.3.1 个人空间接口规范.49 8.4 教育教学应用服务.50 江西省教育资源公共服务平台开放 API 接口规范(V1.0) 8.4.1 网络备课接口.50 8.4.2 区域教研接口.51 8.4.3 公开课接口.52 8.5 第三方数据交换服务.53 8.5.1 传递第三方平台的统计数据.53 8.5.2 传递第三方用户行为数据.53 8.5.3 传递第三方业务数据.54 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -1- 前言江西省教育资源公共服务平台遵循 统筹规划、统一建设、标准 开放 的原则,在逻辑上建立统一的数据中心,建成覆盖全省、稳定 可靠、先进适用的教育资源公共服务平台,面向各类资源及应用提供 统一身份认证,数据共享、空间服务、单点登录、统一监管等基础服 务,形成资源及应用汇聚共享的全省教育信息化公共服务体系. 为确保各类资源及教育应用的正确接入和应用扩展, 真正达到应 用以及资源、数据的共建共享,消除信息孤岛,特制定江西省教育资 源公共服务平台开放的 API 接口规范.通过规范的制定和执行,在全 省建立一个具有统一资源标准、 统一身份认证和统一教育资源索引的 信息通道, 让优质的教育资源和信息可以在各类应用之间真正流动起 来,各级师生及教育工作者在享受优质教育资源的同时,也可方便的 进行沟通和交流, 充分发挥 云 的优势, 促进教育教学和管理创新, 推进教育均衡发展, 提高整体教育质量, 支撑教育信息化可持续发展. 1. 范围 本标准从技术角度资源、数据、应用等方面规定了江西省教育资 源公共服务平台的集成方法,包括总体技术架构、应用接入服务、统 一身份认证以及相关的服务接口参考. 本标准适用于各类教育资源、 应用在接入教育资源公共服务平台 时参考使用. 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -2- 2. 术语、定义和缩略语 接口 interface 两个功能单元之间的共享边界, 该边界由两个功能单元的功能特 性、物理互连特性、信号交换特性及其他适当特性定义. 面向服务架构 service-oriented architecture(SOA) 是一个组件模型,它将应用程序的不同功能单元(称为服务)通 过这些服务之间定义良好的接口和契约联系起来. 接口是采用中立的 方式进行定义的, 独立于实现服务的硬件平台、 操作系统和编程语言. 这使得构建在各种各样的系统中的服务可以使用一种统一和通用的 方式进行交互. 服务 Service SOA 的逻辑组成单元.一个服务就是一个代码模块,由可通过基 于标准的接口访问的服务水平协议管理.每个服务表示一部分功能, 明确地映射业务流程中的一个步骤. 服务可以被其他服务或其他程序 利用. RESTful REST 的全称是 Representation State Transfer,它描述了一种 设计 Web 应用的架构风格,它是一组架构约束条件和原则,满足这些 约束条件和原则的应用程序或设计就是 RESTful 风格的.而符合 RESTful 风格的Web Services , 就是我们所说的RESTful Web Services. 单点登录 Single Sign On(SSO) 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -3- 一种身份管理方法, 是指访问同一体系不同应用中的受保护资源 的同一用户,只需要登录一次,在通过统一的安全验证后,再访问其 他应用中的受保护资源时,不再需要重新登录验证. UGC 数据 全称为 User Generated Content,也就是用户生成内容的意思. UGC 的概念最早起源于互联网领域,即用户将自己原创的内容通过互 联网平台进行展示或者提供给其他用户.UGC 是伴随着以提倡个性化 为主要特点的 Web2.0 概念兴起的. 元数据 Metadata 关于数据的数据.包括用于描述数据含义的数据字典. 应用程序编程接口 Application Programming Interface(API) 是一些预先定义的函数, 目的是提供应用程序与开发人员基于某 软件或硬件的以访问一组例程的能力. SDK SDK(Software Development Kit, 即软件开发工具包 )一般是 一些被软件工程师用于为特定的软件包、软件框架、硬件平台、操作 系统等建立应用软件的开发工具的集合. 3. 开放平台技术架构 江西教育资源公共服务应用平台作为综合性开放服务平台, 需要 针对各类资源及教育应用接入提供统一标准,具体如下图所示. 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -4- 开放平台服务框架图 江西省教育资源公共服务平台采用面向服务的体系架构, 通过业 务服务的方式向其他资源及教育应用提供教育信息共享互联互通的 各项基本功能. 在平台公共支撑服务的基础上,将部分基础数据、个人空间、数 字教育资源等通过开放平台架构以服务形式对外提供, 各类资源及教 育应用在授权范围内进行接入和集成, 平台对资源及应用的调用进行 监管,从而达到资源汇聚共享、空间贯通、管理监管的目的. 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -5- 4. 第三方应用接入流程 4.1 线上接入申请流程 应用接入流程图 ? 应用提供方提交接入相关资料,审核通过后,平台为第三方应用 分配 APP_NAME 和APP_SECRET.注意:APP_NAME 与APP_SECRET 请 妥善保管,防止泄露被非法盗用. 附:应用接入申请表: 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -6- 江西省教育资源公共服务平台应用接入申请表 2017/8/10 V1.0 应用中文名称 应用英文名称 由数字或字母组成,全部小写,长度小于

20 个字符 应用类型(单选) 站内应用 外部站点 所属学段 学前 小学 初中 高中 适用对象 所有人 教师 学生 教育管理者 应用分类 备课授课 互动课堂 协作互动 网络课程 网络教研 作业测评 语言学习 数字图书馆 是否收费 免费应用 收费应用 使用权限 所有人 指定市: 指定区县: 指定学校: 应用回调地址 请提供回调接口完整地址 联系方式 应用介绍 应用接入内容 (数据范围 需调用的接口) 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -7- ? 应用提供方下载对应开发语言的 SDK 开发包,进行具体的应用开 发工作,开发过程中可连接到调试服务器进行应用调试,遇到平 台相关的问题也可联系技术支持共同解决. ? 开发调试完成后,提交应用上线申请,审核通过后正式上线运营. ? 平台对于不同的应用可设置不同的使用权限范围,应用所有的接 口调用都在平台监管下执行. 4.2 线下申请流程 在开放平台资料下载中,下载《江西省教育资源公共服务平台开 放开发平台对接申请表》 ,提交主管单位审核. 4.3 API 使用规范 为了更好的保障线上应用良好的用户体验, 请开发者按照此规范 对开放平台 API 进行合理使用. 若因违规调用相关 API 导致用户体验 受到不良影响, 平台有权按照相应处理办法对违规调用接口的应用进 行处理.API 使用规范如下: ? 对于用户信息、好友关系类接口需谨慎使用,不得将用户信息用 于除应用功能所需之外的一切用途. ? 不得在用户不知情的情况下以用户身份进行发布动态、相册、状态,给好友发消息等. ? 不得在授权范围外对系统进行恶意调用,安全攻击等. ? API 使用规范包含但不限于以上条目,任何影响用户体验、网站 安全的功能都将被视为违规情况. 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -8- 4.4 接入方式 (1)接入的标准规范 应用必须符合法律法规,不侵犯其他第三方和平台的权益,在接 入申请后,请在应用的相关网页上增加 使用赣教云账号登录 按钮 的尺寸和图标赣教云的登录地址等信息, 且保证平台用户登录后能直 接进入应用,不需要再做其他额外的绑定激活等操作. (2)单点登录模式 该模式依托服务体系的身份认证服务和基础数据服务, 接入的平 台可专注于自身的业务扩展, 无需关注基础数据的管理和用户认证服 务,业务所需的基础数据均来自于服务体系,用户的认证使用服务体 系统一的身份认证入口. 该认证方式需要平台同步服务体系的基础数 据,详见基础数据规范和数据交换规范. (3)OAuth认证模式 该模式依托服务体系的 OAuth 认证服务, 接入的平台有自身的用 户体系和认证服务,平台可以使用自身账号登录,也可以使用服务体 系的账号进行登录;

用户第一次使用体系账号在平台登录时,在平台 形成账号绑定关系,以后登录则无需再次绑定. 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -9- (4)应用接入方式 应用接入登录流程图 ? 对于已经在运营的应用系统,为便于和江西省教育资源公共服务 平台打通用户数据,在登录江西省教育资源公共服务平台后访问 平台网站,登录状态会保持. 1) 由于与江西省教育资源公共服务平台的单点登录服务已打通, 如果用户已经在其他页面登录到江西省教育资源公共服务平 台,返回到则自动显示已登录用户信息. 否则会提示用户输入用户名和密码: 江西省教育资源公共服务平台开放 API 接口规范(V1.0) -10- 2) 用户成功登录江西省教育资源公共服务平台后,页面自动回到 登录前页面. ? 在账号绑定成功后,用户登录系统后,便可通过已绑定的江西省 教育资源公共服务平台用户 ID 通过调用江西省教育资源公共服 务平台开放 API 接口获取相关的用户数据,并呈........