Skip to main content

一、接入概述​

1、简述​

平台为开发人员提供了接入第三方应用与平台数据对接的完善解决方案。开发人需要仔细阅读提供的统一认证和API接口文档，以保顺利完成接入工作。

2、接入流程​

二、统一认证接入​

1、简述​

统一用户认证（单点登录）是指用户在认证中心登录后，即同时登录到所有与此认证中心关联的所有服务中。

目前平台目前提供两种统一认证方式：Ticket登录和OAuth登录。

OAuth登录是一个开放标准统一认证，Ticket登录与OAuth类似，是对OAuth登录方式的简化。第三方应用可以根据自身情况选择不同认证方式进行登录。

平台用户端：区域端，教职工端，学生端，家长端

2、应用创建​

开发人员提交应用创建申请，平台管理员审核并在学校的平台中启用第三方应用。

第三方应用需提供内容：

应用名称：例如：智能排课

应用描述：例如：只需5步帮您排出满意的课表,最先进的算法,满足最详细的排课要求

用户端：区域端，教职工端，学生端，家长端

跳转地址：第三方回调地址【如有PC和移动两个访问地址，分别提供】

icon： 应用的图标【JPG/PNG格式/104*104px以上/长宽1:1/2MB以下的图标】

3、接口调用​

名词解释​

${SSOURL} ：第三方回调地址

${BASEURL}：平台提供的域名地址

Ticket登录示例​

1.请求地址：${SSOURL}&ticket=a69c8765f1b7cc2fc3c66a3

完整地址：https://third.sso.com/login/auth&ticket=a69c8765f1b7cc2fc3c66a3

2.请求地址：${BASEURL}/nicezhuanye/ssoLogin/ticket?ticket=a69c8765f1b7cc2fc3c66a3

完整地址：https://pt.com/nicezhuanye/ssoLogin/ticket?ticket=a69c8765f1b7cc2fc3c66a3

OAuth2登录示例​

1.请求地址：${BASEURL}/login/oAuthLogin.html

完整地址：https://third.sso.com/login/oAuthLogin.html?grant_type=authorization_code&response_type=code&appkey=mi46ro0bts&state=1234&redirect_uri=https://www.baidu.com

2.获取授权令牌信息：${BASEURL}/loginserv/oauth/connect/token

3.获取用户信息：${BASEURL}/loginserv/oauth/userinfo

小提示

注意：在获取ACCESS_TOKEN时，API接口与Oauth2授权模式不同。

4、联调测试​

平台提供测试地址账号密码给开发人员，开发人员登录学校应用中心进行登录测试。

三、API接入​

1、简述​

开发人员根据产品需求选择API接口申请开通，通过API接口同步基础数据和业务数据。

2、接口申请​

平台开通API接口后，提供请求地址baseUrl，appKey，appSecret参数，没有授权的接口暂时无法调用。

名词解释​

${BASEURL} ：平台提供的请求地址前缀

appKey：平台提供的唯一标识

appSecret：平台提供的密钥

示例​

例如：请求地址：${BASEURL}/dataconnectorserv/integration/basic/getSchools

学校列表完整地址 https://school.nicezhuanye.com/dataconnectorserv/integration/basic/getSchools

接口中studentEID，teacherEID，parentEID 可以根据平台ID，登录名，第三方厂商ID三种方式切换。

名词解释​

平台ID ：平台提供ID

登录名：平台提供登录名

  • 学生：学校学号/学籍号/身份证号
  • 教师：手机号/教师编号/身份证号
  • 家长：手机号

第三方厂商ID：来源于第三方提供的数据ID

示例​

1.平台提供ID

  • "studentEID": "LkTjFVQgt3+/w0HSsfA9E+Q=="
  • "teacherEID": "LkTjFVQgt3+/w0HSsfA9E+Q=="
  • "parentEID": "LPMR/VV9EKAP22HrmJgidGA=="

2.登录名

  • "studentEID": "20231020 | G6227272202310201X | 6227272202310201X"
  • "teacherEID": "13020231020 | 20231020 | 6227272202310211X"
  • "parentEID": "13020231022"

3.第三方厂商ID

  • "studentEID": "b80d99332fb82fc76dabf864b1796a45"
  • "teacherEID": "b80d99332fb82fc76dabf864b1796a45"
  • "parentEID": "b80d99332fb82f2c76dabf864b1796a47"

3、接口调用​

开发人员可以使用工具Postman进行模拟请求。

步骤1：请求API接口时，首先获取access_token参数。

步骤2：将headers设置为Authorization={access_token} 或 API接口地址添加${BASEURL}?access_token={access_token}。

步骤3：请求的参数为json格式（application/json），放在body中。

3.1、获取接口授权​

基本信息​

接口名称：获取Token接口授权

接口说明：根据平台提供appKey，appSecret获取接口授权token

请求地址：${BASEURL}/loginserv/oauth/connect/token

请求方式：POST

请求类型：application/x-www-form-urlencoded

接口版本：1.0

修改日期：2023-12-05

请求参数​
参数名数据类型是否必填说明
grant_typeString是授权模式，固定传client_credentials
appKeyString是平台唯一标识
appSecretString是平台唯一密钥
小提示

注意：在获取ACCESS_TOKEN时，API接口与Oauth2授权模式不同。

响应结果​
{
    "code": 0,
    "status": "success",
    "result": {
        "expires_in": 300,
        "access_token": "wWLYgKBRsg2PGUMF8afhIFG6J4wnstMwuyHmouocizffqFxMD0X9TOxzZ9gY"
    }
}

3.2、设置API授权​

小提示【重要！】

API请求权限，两种方式皆可：

1、Headers设置为Authorization={access_token}

2、API接口地址添加${BASEURL}?access_token={access_token}

3.3、请求API接口​

学校列表|区域列表​
参数名类型是否必填说明
appKeyString是平台提供的唯一标识
学校基础数据|学校业务接口​
参数名类型是否必填说明
appKeyString是分配厂商appKey，平台提供
schoolIDString是学校ID，从学校列表获取，基础数据和业务接口
gradeIDString否年级ID，根据每个接口情况是否填写，例如：学生成绩接口
sourceIDString否数据源ID，获取数据源数据接口使用

4、联调测试​

步骤1：获取授权接口​

步骤2：设置API授权​

步骤3：请求API接口​
学校列表|区域列表​

学校基础数据|学校业务数据​