Skip to main content

一、使用场景​

消息通知场景：第三方服务使用平台基础数据，需要及时更新基础数据，则提供消息通知使第三方能够及时获取最新数据进行更新。

消息通知简述：第三方服务通过平台提供消息接口进行注册，注册后，平台基础数据等数据变更时通知第三方服务【延迟5分钟内】，第三方服务接受到平台消息并更新基础数据。

消息类型说明：消息通知可以注册多个消息事件，注册会覆盖上一次注册信息，以最后注册信息为准。

通知类型通知名称通知内容说明年级变更
gradeChange年级变更新建年级，年级名称发生变化√
adminClassChange行政班变更新建分班记录，班级名称发生变化√
teachingClassChange教学班变更新建分班记录，班级名称发生变化√
crossGradeTeachingClassChange选修班变更新建分班记录，班级名称发生变化
stuChange学生变更新增学生，修改学生，禁用学生，学生调班√
teacherChange老师变更新增教师，修改教师 ，删除教师，添加教师执教班级，添加角色
scheduleChange课表变更课表发布，调课有变化通知√
timeSettingChange作息变更作息有变化通知
appChange应用变更第三方应用通知，额外开发，默认不通知
schoolChange学校变更学校开通应用通知，默认不通知
parentChange家长变更家长增加，修改，删除通知
locationChange场地变更场地增加，修改，删除通知
all全部变更以上数据全部有变化时通知（订阅全部变更，并不会推送all类型）
firmChange厂商变更学校列表添加学校后，学校不用单独注册通知，默认给授权学校通知消息
小提示

√：表示年级变更表示通知时候会传递参数gradeID，则其他通知不传递gradeID。

all：表示所有变更都通知。

firmChange：表示厂商变更通知，不用每个学校单独注册通知（平台添加新学校授权就可以通知）。

msgTypes：[ "firmChange", "all"] 表示所有厂商开通的学校且所有通知类型都通知，推荐使用。

二、注册消息通知​

接口名称：注册消息通知

接口说明：每次可以注册多个消息事件，每次注册会覆盖之前的注册信息

请求地址：${BASEURL}/dataconnectorserv/message/notification/regMsg

请求方式：POST

请求类型：application/json

接口版本：1.0

修改日期：2020-06-28

1、请求参数：​

参数名类型是否必填说明
appKeyString是平台提供的唯一标识
schoolIDString否学校ID，厂商注册时不需要学校ID
messageObject是注册消息
msgTypesArray是消息类型：每次注册覆盖上一次信息，以最后一次为准
sendURLString是推送地址：第三方推送URL
sendConnectionString是请求协议：http或https
methodString是请求方式：POST 或 GET
authParamsString否第三方自定义参数，需JSON格式转换字符串类型
{
    "appKey": "36s2zllw",
    "schoolID":"wca5opSRt2tyyBSLqOjdoS==",
    "message": {
        "msgTypes": [
            "firmChange",
            "all"
        ],
        "sendURL": "https://mysqltest.nicezhuanye.com/api/pub/exp/school/data",
        "sendConnection": "https",
        "method": "POST",
        "authParams": "{\"appID\":\"36vxzplw\",\"appScecret\":\"1GasIqmukiE/Zc8+fSVyP+eg=\",\"dictKey\":\"hzy\"}"
    }
}

2、响应结果​

{
   "code":0,
   "status":"success"
}

三、获取注册信息​

接口名称：获取注册消息通知信息

请求地址：${BASEURL}/dataconnectorserv/message/notification/getRegMsg

请求方式：POST

请求类型：application/json

接口版本：1.0

修改日期：2020-06-28

1、请求参数：​

参数名类型是否必填说明
appKeyString是平台提供的唯一标识
schoolIDString是学校ID，从学校列表获取
{
    "appKey":"36s2zllw",
    "schoolID":"wca5opSRt2tyyBSLqOjdoS=="
}

2、响应结果​

{
    "code": 0,
    "status": "success",
    "result": [
        {
            "schoolID": "null",
            "msgTypes": [
                "firmChange",
                "all"
            ],
            "sendURL": "https://mysqltest.nicezhuanye.com/api/pub/exp/school/data",
            "sendConnection": "https",
            "method": "POST",
            "authParams": "{\"appID\":\"36vxzplw\",\"secretKey\":\"1GasIqmukiE/Zc8+fSVyP+eg=\",\"dictKey\":\"nicezhuanye\"}",
            "updateTime": "2023-11-02 18:14:03"
        }
    ]
}

四、推送消息【平台通知消息】​

接口名称：推送消息

接口说明：平台数据变更时会异步推送消息至第三方服务，第三方服务判断消息类型同步更新基础数据或课表数据等内容

请求地址：第三方服务注册的地址sendURL

请求方式：POST

请求类型：application/json

接口版本：1.0

修改日期：2020-06-28

1、请求参数​

参数名类型是否必填说明
schoolIDString是学校ID，接口列表学校ID
gradeIDString否年级ID
messageTypeString是消息类型，注册消息类型
{
  "schoolID": "wca5opSRt2tyyBSLqOjdoS==",
  "gradeID": "10102023",
  "messageType": "classChange",
  // 需要传给第三方定制参数，默认无
  "appID":"123",  // 根据注册信息识别第三方定制参数
  "appSecret":"123456", // 根据注册信息识别第三方定制参数
}

2、响应结果​

{
  "code": 0,
  "status": "success"
}

五、获取推送消息历史记录​

接口名称：获取推送消息历史记录

接口说明：平台或第三方获取推送历史记录，包括成功或失败的推送结果

请求地址：${BASEURL}//dataconnectorserv/message/notification/getMsgHistory

请求方式：POST

请求类型：application/json

接口版本：1.0

修改日期：2020-06-28

1、请求参数​

参数名类型是否必填说明
appKeyString是平台提供的唯一标识
schoolIDString是学校ID，从学校列表获取
{
    "appKey":"36s2zllw",
    "schoolID":"wca5opSRt2tyyBSLqOjdoS=="
}

2、响应结果​

{
    "code": 0,
    "status": "success",
    "result": [
        {
            "schoolID": "1110",
            "gradeID": "1012018",
            // 注册消息通知类型
            "msgTypes": [
                "classChange",
                "scheduleChange"
            ],
            // 实际变更数据类型
            "changeType": "scheduleChange",
            // 推送状态
            "status": "success",
            "updateTime": "2020-06-29 15:31:28"
        },
        {
            "schoolID": "1110",
            "gradeID": "1012018",
            "msgTypes": [
                "classChange",
                "scheduleChange"
            ],
            "changeType": "classChange",
            "status": "fail",
            "updateTime": "2020-06-29 15:33:15"
        }
    ]
}