# AIUI 后处理协议

# 后处理概述

AIUI 后处理是为AIUI开发者提供更方便的后台接入能力,能够根据语音听写或语义等结果,提供个性化的服务和资讯。而开放平台协议则是提供此类服务的基础。在申请获取后处理权限后,可以参考此文档进行服务平台开发。

# 服务器接入验证

为了确认开发者服务器地址是否可用,所以需要在配置保存时进行验证,开发者服务器需要

开发者接入服务器验证流程。

  1. 开发者提交信息后,AIUI服务器将发送GET请求到填写的服务器地址URL上。 GET请求携带参数如下面所示:
参数 描述
signature 加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、rand参数。
timestamp 时间戳
rand 随机数
  1. 开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自AIUI服务器,请返回开放平台中token值的sha1参数内容,则接入生效,成为开发者成功,否则接入失败。

加密/校验流程如下:

  • 将token、timestamp、rand三个参数值进行字典序排序

  • 将三个参数字符串拼接成一个字符串进行sha1加密

  • 开发者获得加密后的字符串可与signature对比,标识该请求来源于AIUI服务

响应消息:

  • 将token进行sha1加密

  • 将加密后的内容字符串放在响应消息的body中

  • 将消息返回即可

注意

校验流程是可选操作,但消息返回必须正确才能校验成功

# 接收消息

当AIUI正常服务完成时,AIUI服务器会按照此协议把服务结果的消息内容POST到开发者填写的URL上。 请注意:

  1. 消息重试:每条消息最长超时时间为3秒,3秒后将会断开连接并进行重试,共2次,如果2次均无响应将返回超时消息的结果到客户端。

  2. 消息排重:每条消息会有一个消息id,对应服务的会话标识,请根据消息主体中的MsgId和CreateTime两者结合进行排重。(MsgId为字符串,CreateTime为整数)

  3. 消息响应:AIUI原样返回开发者服务响应数据到AIUI客户端。

  4. 消息签名:仅用于检验AIUI请求发出消息的完整性,不用于校验开发者服务响应消息。签名是由token+timestamp+rand+postbody 进行字典排序,然后sha1生成的,token为开发者设定的唯一标识,timestamp为时间戳,srand为固定字节随机串,postbody为post接收到的body消息。 url中的msgsignature参数存储了签名信息。timestamp和rand参数也在url里。

  5. 消息加密:当在AIUI平台配置了加密功能,会自动生成一个aeskey,此时发送给开发者服务器的数据是经过加密的,且在请求的url中的encrypttype参数值为“aes”(非加密时参数值为raw)。请在解析消息前要对消息进行解密。同时开发者服务器给AIUI返回的结果也要用同一个aeskey进行加密,AIUI返给客户端的数据是解密后的数据。

  6. 消息格式

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秘钥进行消息的解密。

  1. 加密采用AES的CBC加密方式,秘钥为16字节(128bit),初始化向量复用秘钥,填充方式为PKCS7Padding。
  2. 返回的消息要以同样的方式进行加密。