检测任务提交
更新时间:
参数规范
- 请求 URL:
https://tsafe.ilivedata.com/api/v1/text/async/check/submit
- HTTP 请求Header:
Header
值
是否必需
描述
Content-Type
application/json;charset=UTF-8
必需
请求体类型
Accept
application/json;charset=UTF-8
必需
接受的返回类型
X-AppId
必需
项目的唯一标识,此值是 <控制台-服务配置>中的项目编号
X-TimeStamp
必需
请求的UTC时间戳。需要把时间戳按W3C标准格式化,例如: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime)。
Authorization
必需
签名值
-
请求方法:
POST
-
请求体JSON:
参数
是否必需
类型
描述
content
必需
String
检测的文本,此文本为不超过2048个字符的UTF-8编码字符串
strategyId
可选
String
策略编号,不传时使用默认策略DEFAULT
country
可选
String
国家代码,不传时使用默认
userId
可选
String
唯一的终端用户ID,用户ID应当不超过64个字符
sessionId
可选
String
用户会话ID,会话ID应当不超过64个字符。
receiverId
可选
String
接收者ID,接收者ID应当不超过64个字符。
userName
可选
String
用户名、昵称,用户名应当不超过32个字符。
userLevel
可选
Number
用户等级
totalPay
可选
Number
用户充值金额,最多支持小数点后2位
registrationDate
可选
Number
用户注册时间,10位数时间戳
msgCount
可选
Number
消息发送次数
msgType
可选
String
消息类型
pkgChannel
可选
String
安装包渠道
userIp
可选
String
用户IP地址
did
可选
String
用户设备ID
dtype
可选
String
用户设备类型:1:iPhone 2:android 3: ipad 4:wphone 5: pc 6:web 7:wap
extra
可选
map类型
其他内容,可以传多个key和value。比如传游戏服务器和游戏版本两个参数,传入方式:“extra” : {“server”: “123”,“version”:“456”}
checkTags
可选
数组类型
检测的类别,支持传入一级类别,100:涉政,110:暴恐,120:违禁,130:色情,150:广告,160:辱骂,170:仇恨言论,180:未成年保护,190:敏感热点,220:私人交易,410: 违规表情,420:昵称相关,999:自定义
callbackUrl
可选
String
回调地址(不推荐,建议在控制台配置回调地址以及密钥)
callbackSecretKey
可选
String
回调密钥(不推荐,建议在控制台配置回调地址以及密钥)
- 请求体示例:
{
"content": "fuck you",
"userId":"1234556",
"strategyId":"123"
}
- 请求签名:
当用户请求Text Check API时,可以使用appId和secretKey对请求做签名,当API收到带签名信息的请求之后,将使用相同的算法验证签名,如果发现签名不一致,API将会返回401给用户。
如果API验证签名一致,且appId对应的用户有权限操作请求的资源,则请求成功,否则API返回401。
- 通过 HTTP 请求 Header 发送签名
方法: 在请求中加入名为 Authorization 的 Header,值为签名值。如下:
Authorization: ****
- 签名计算方法
- 构造规范化的请求字符串(Canonicalized Query String)::
将请求体JSON字符串以UTF-8字符编码做sha256编码后转换为16进制字符串(注意不是Base64)
CanonicalizedQueryString = hex(sha256(jsonBody))
-
构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符)
StringToSign = HTTPMethod + “\n” +
HostHeaderInLowercase + “\n” +
HTTPRequestURI + “\n” +
CanonicalizedQueryString <从上一步得到> + “\n” +
“X-AppId:” + SAME_APPID_IN_HEADER + “\n” +
“X-TimeStamp:” + SAME_TIMESTAMP_IN_HEADER
HTTPRequestURI是请求URI的绝对路径,不包含请求串。如果HTTPRequestURI为空,也要保留一个正斜杠 ( / )
使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC),然后计算签名。
-
StringToSign作为签名字符串,secretKey作为秘钥,SHA256作为哈希算法
有关 HMAC 的更多信息,请参阅 https://tools.ietf.org/html/rfc2104。
-
将上一步的结果转换为BASE64串
-
将BASE64串放入HTTP请求Header的Authorization
- 签名示例
下面是appId & secretKey & content的示例
appId=***
secrectKey=****
content="fuck you"
userId=1235678
下面是示例请求体
{
"content":"fuck you",
"userId": "12345678",
"checkTags": [150,160]
}
生成CanonicalizedQueryString
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
生成StringToSign
POST
tsafe.ilivedata.com
/api/v1/text/check
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:1000
X-TimeStamp:2020-07-31T07:59:03Z
HMAC计算得到的签名
*****
HTTP响应
Content-Type: application/json;charset=UTF-8
结果为JSON格式,请参考以下示例。
- HTTP响应示例:
返回JSON字段说明:
字段名
类型
描述
errorCode
Number
错误码,0表示成功
errorMessage
String
错误消息
taskId
String
区分不同次调用的唯一标识
- 响应示例:
{
"errorCode": 0,
"taskId": "us_**************************"
}
错误码
Http状态码
错误码
错误消息
错误原因
200
0
此字段省略
429
1104
Out of Rate Limit
请求频率超过限制(20次/秒);请求文本字符总数超过频率限制(长度超过100的字符总数: 1K字符/秒);
405
1004
Method Not Allowed
http请求的method只能是get或者post。为post时,header里必须有content-type,且值为application/x-www-form-urlencoded
411
1007
Not Content Length
http请求的method为post时,header里必须设置正确的content-length
400
1002
API Not Found
根据http请求的path没有找到相应的API
400
1003
Bad Request
解析request失败
400
2000
Missing Parameter
json缺少参数content
400
2102
Input Too Long
json参数content长度超过限制
401
1102
Unauthorized Client
参数X-AppId无效
401
1106
Missing Access Token
没有Authorization
401
1107
Invalid Token
Authorization不正确
401
1108
Expired Token
X-TimeStamp过期
401
2000
Missing Parameter
缺少X-TimeStamp
401
2001
Invalid Parameter
X-TimeStamp格式错误
参数规范
- 请求 URL:
https://tsafe.ilivedata.com/api/v1/text/async/check/submit
- HTTP 请求Header:
Header | 值 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | application/json;charset=UTF-8 | 必需 | 请求体类型 |
Accept | application/json;charset=UTF-8 | 必需 | 接受的返回类型 |
X-AppId | 必需 | 项目的唯一标识,此值是 <控制台-服务配置>中的项目编号 | |
X-TimeStamp | 必需 | 请求的UTC时间戳。需要把时间戳按W3C标准格式化,例如: 2010-01-31T23:59:59Z. (http://www.w3.org/TR/xmlschema-2/#dateTime)。 | |
Authorization | 必需 | 签名值 |
-
请求方法: POST
-
请求体JSON:
参数 | 是否必需 | 类型 | 描述 |
---|---|---|---|
content | 必需 | String | 检测的文本,此文本为不超过2048个字符的UTF-8编码字符串 |
strategyId | 可选 | String | 策略编号,不传时使用默认策略DEFAULT |
country | 可选 | String | 国家代码,不传时使用默认 |
userId | 可选 | String | 唯一的终端用户ID,用户ID应当不超过64个字符 |
sessionId | 可选 | String | 用户会话ID,会话ID应当不超过64个字符。 |
receiverId | 可选 | String | 接收者ID,接收者ID应当不超过64个字符。 |
userName | 可选 | String | 用户名、昵称,用户名应当不超过32个字符。 |
userLevel | 可选 | Number | 用户等级 |
totalPay | 可选 | Number | 用户充值金额,最多支持小数点后2位 |
registrationDate | 可选 | Number | 用户注册时间,10位数时间戳 |
msgCount | 可选 | Number | 消息发送次数 |
msgType | 可选 | String | 消息类型 |
pkgChannel | 可选 | String | 安装包渠道 |
userIp | 可选 | String | 用户IP地址 |
did | 可选 | String | 用户设备ID |
dtype | 可选 | String | 用户设备类型:1:iPhone 2:android 3: ipad 4:wphone 5: pc 6:web 7:wap |
extra | 可选 | map类型 | 其他内容,可以传多个key和value。比如传游戏服务器和游戏版本两个参数,传入方式:“extra” : {“server”: “123”,“version”:“456”} |
checkTags | 可选 | 数组类型 | 检测的类别,支持传入一级类别,100:涉政,110:暴恐,120:违禁,130:色情,150:广告,160:辱骂,170:仇恨言论,180:未成年保护,190:敏感热点,220:私人交易,410: 违规表情,420:昵称相关,999:自定义 |
callbackUrl | 可选 | String | 回调地址(不推荐,建议在控制台配置回调地址以及密钥) |
callbackSecretKey | 可选 | String | 回调密钥(不推荐,建议在控制台配置回调地址以及密钥) |
- 请求体示例:
{
"content": "fuck you",
"userId":"1234556",
"strategyId":"123"
}
- 请求签名:
当用户请求Text Check API时,可以使用appId和secretKey对请求做签名,当API收到带签名信息的请求之后,将使用相同的算法验证签名,如果发现签名不一致,API将会返回401给用户。
如果API验证签名一致,且appId对应的用户有权限操作请求的资源,则请求成功,否则API返回401。
- 通过 HTTP 请求 Header 发送签名
方法: 在请求中加入名为 Authorization 的 Header,值为签名值。如下:
Authorization: ****
- 签名计算方法
- 构造规范化的请求字符串(Canonicalized Query String)::
将请求体JSON字符串以UTF-8字符编码做sha256编码后转换为16进制字符串(注意不是Base64)
CanonicalizedQueryString = hex(sha256(jsonBody))
-
构造被签名字符串 StringToSign ("\n" 代表ASCII里的换行符)
StringToSign = HTTPMethod + “\n” + HostHeaderInLowercase + “\n” + HTTPRequestURI + “\n” + CanonicalizedQueryString <从上一步得到> + “\n” + “X-AppId:” + SAME_APPID_IN_HEADER + “\n” + “X-TimeStamp:” + SAME_TIMESTAMP_IN_HEADER
HTTPRequestURI是请求URI的绝对路径,不包含请求串。如果HTTPRequestURI为空,也要保留一个正斜杠 ( / )
使用 HMAC-SHA256 协议创建基于哈希的消息身份验证代码 (HMAC),然后计算签名。
-
StringToSign作为签名字符串,secretKey作为秘钥,SHA256作为哈希算法
有关 HMAC 的更多信息,请参阅 https://tools.ietf.org/html/rfc2104。
-
将上一步的结果转换为BASE64串
-
将BASE64串放入HTTP请求Header的Authorization
- 签名示例
下面是appId & secretKey & content的示例
appId=***
secrectKey=****
content="fuck you"
userId=1235678
下面是示例请求体
{
"content":"fuck you",
"userId": "12345678",
"checkTags": [150,160]
}
生成CanonicalizedQueryString
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
生成StringToSign
POST
tsafe.ilivedata.com
/api/v1/text/check
b3ad8e9d16439ccd5e91924d2516bf9592975003f69beff44e56cddf47bd3118
X-AppId:1000
X-TimeStamp:2020-07-31T07:59:03Z
HMAC计算得到的签名
*****
HTTP响应
Content-Type: application/json;charset=UTF-8
结果为JSON格式,请参考以下示例。
- HTTP响应示例:
返回JSON字段说明:
字段名 | 类型 | 描述 |
---|---|---|
errorCode | Number | 错误码,0表示成功 |
errorMessage | String | 错误消息 |
taskId | String | 区分不同次调用的唯一标识 |
- 响应示例:
{
"errorCode": 0,
"taskId": "us_**************************"
}
错误码
Http状态码 | 错误码 | 错误消息 | 错误原因 |
---|---|---|---|
200 | 0 | 此字段省略 | |
429 | 1104 | Out of Rate Limit | 请求频率超过限制(20次/秒);请求文本字符总数超过频率限制(长度超过100的字符总数: 1K字符/秒); |
405 | 1004 | Method Not Allowed | http请求的method只能是get或者post。为post时,header里必须有content-type,且值为application/x-www-form-urlencoded |
411 | 1007 | Not Content Length | http请求的method为post时,header里必须设置正确的content-length |
400 | 1002 | API Not Found | 根据http请求的path没有找到相应的API |
400 | 1003 | Bad Request | 解析request失败 |
400 | 2000 | Missing Parameter | json缺少参数content |
400 | 2102 | Input Too Long | json参数content长度超过限制 |
401 | 1102 | Unauthorized Client | 参数X-AppId无效 |
401 | 1106 | Missing Access Token | 没有Authorization |
401 | 1107 | Invalid Token | Authorization不正确 |
401 | 1108 | Expired Token | X-TimeStamp过期 |
401 | 2000 | Missing Parameter | 缺少X-TimeStamp |
401 | 2001 | Invalid Parameter | X-TimeStamp格式错误 |