# AIUI 后处理协议
# 后处理概述
AIUI 后处理是为AIUI开发者提供更方便的后台接入能力,能够根据语音听写或语义等结果,提供个性化的服务和资讯。而开放平台协议则是提供此类服务的基础。在申请获取后处理权限后,可以参考此文档进行服务平台开发。
# 服务器接入验证
为了确认开发者服务器地址是否可用,所以需要在配置保存时进行验证,开发者服务器需要
开发者接入服务器验证流程。
- 开发者提交信息后,AIUI服务器将发送GET请求到填写的服务器地址URL上。 GET请求携带参数如下面所示:
参数 | 描述 |
---|---|
signature | 加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、rand参数。 |
timestamp | 时间戳 |
rand | 随机数 |
- 开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自AIUI服务器,请返回开放平台中token值的sha1参数内容,则接入生效,成为开发者成功,否则接入失败。
加密/校验流程如下:
将token、timestamp、rand三个参数值进行字典序排序
将三个参数字符串拼接成一个字符串进行sha1加密
开发者获得加密后的字符串可与signature对比,标识该请求来源于AIUI服务
响应消息:
将token进行sha1加密
将加密后的内容字符串放在响应消息的body中
将消息返回即可
注意
校验流程是可选操作,但消息返回必须正确才能校验成功
# 接收消息
当AIUI正常服务完成时,AIUI服务器会按照此协议把服务结果的消息内容POST到开发者填写的URL上。 请注意:
消息重试:每条消息最长超时时间为3秒,3秒后将会断开连接并进行重试,共2次,如果2次均无响应将返回超时消息的结果到客户端。
消息排重:每条消息会有一个消息id,对应服务的会话标识,请根据消息主体中的MsgId和CreateTime两者结合进行排重。(MsgId为字符串,CreateTime为整数)
消息响应:AIUI原样返回开发者服务响应数据到AIUI客户端。
消息签名:仅用于检验AIUI请求发出消息的完整性,不用于校验开发者服务响应消息。签名是由token+timestamp+rand+postbody 进行字典排序,然后sha1生成的,token为开发者设定的唯一标识,timestamp为时间戳,srand为固定字节随机串,postbody为post接收到的body消息。 url中的msgsignature参数存储了签名信息。timestamp和rand参数也在url里。
消息加密:当在AIUI平台配置了加密功能,会自动生成一个aeskey,此时发送给开发者服务器的数据是经过加密的,且在请求的url中的encrypttype参数值为“aes”(非加密时参数值为raw)。请在解析消息前要对消息进行解密。同时开发者服务器给AIUI返回的结果也要用同一个aeskey进行加密,AIUI返给客户端的数据是解密后的数据。
消息格式:
HTTP消息格式定义如下:
POST /yourserveruri?xx=xx HTTP 1.1
Connection: close
Host:xxx.xxx.xxx
Content-Type: application/json
Content-Length: 111
{消息主体}
TIP
可以根据Content-Type的类型来解析相应的消息主体。例如:当POST请求的Content-Type为application/json时,要根据Json格式解析消息主体。
消息主体格式
{
"MsgId":"1234567",
"CreateTime":1348831860,
"AppId":"12345678",
"UserId":"d123455",
"SessionParams":"Y21kPXNzYixzdWI9aWF0LHBsYXRmb3JtPWFuZG9yaWQ=",
"UserParams":"PG5hbWU+eGlhb2JpYW5iaWFuPC9uYW1lPg==",
"FromSub":"iat",
"Msg":{},
}
格式说明
参数 | 描述 |
---|---|
MsgId | 消息id,字符串类型 |
CreateTime | 消息创建时间,整型 |
AppId | 开发者应用Id,字符串类型 |
UserId | AIUI唯一用户标注,字符串类型 |
UserParams | 开发者自定义参数,通过客户端的userparams参数上传,Base64格式字符串 |
FromSub | 上游业务类型,目前包括两种(iat:听写结果,kc:语义结果),字符串类型 |
Msg | 消息内容,json object参考Msg消息内容格式 |
SessionParams | 本次会话交互参数,Base64格式字符串,解码后为json格式 |
Msg消息内容格式
文本内容
{
"Type":"text",
"ContentType":"Json",
"Content":"eyJzbiI6MiwibHMiOnRydWUsImJnIjowLCJlZCI6MCwid3MiOlt7ImJnIjowLCJjdyI6W3sic2MiOjAsInciOiLvvJ8ifV19XX0="
}
参数 | 描述 |
---|---|
Type | text |
ContentType | 内容格式,Json plain xml |
Content | Base64内容字符串 |
# 接入指引
# 消息校验使用方法
当收到消息响应时,可以从url参数中取得以下四个参数,都为字符串类型,用于验证消息完整性
参数 | 描述 | 来源 |
---|---|---|
msgsignature | 签名信息 | 存储消息的签名 |
timestamp | 时间戳 | 由平台生成 |
rand | 随机字符串 | 平台随机生成的随机串 |
encrypttype | 加密类型 | 由页面配置决定(目前支持raw和aes) |
验证消息的过程(伪代码)
int message_sigcheck(token ,msgsignature ,timestamp ,srand ,data)
{
//对参数进行字典排序
vector<std::string> s(4);
for (){ // 将参数token,timestamp,srand,data放入字典}
//字典排序
sort(s.begin(), s.end());
//链接字符
std::string str;
for (){ // 将四个s里的值按顺序链接到str里}
//对str进行sha1
std::string signature = Sha1(str.c_str());
//校验签名字符串 0为一致,-1为不一致
return signature.compare(msgsignature)?-1:0;
}
注意:消息校验是开发者用来校验消息的完整性,为了消息的安全,建议使用校验。
# 消息加解密相关说明
当平台勾选加密时,请求给开发者服务器的body是加密后的。需要使用平台提供的AES秘钥进行消息的解密。
- 加密采用AES的CBC加密方式,秘钥为16字节(128bit),初始化向量复用秘钥,填充方式为PKCS7Padding。
- 返回的消息要以同样的方式进行加密。