网易易盾手游智能反外挂文本检测(服务端)接入文档

2022.11.28 13:45:41

    一、接入说明

    1.1.文本接口调用流程

    易盾内容安全文本检测服务对外提供在线实时检测和离线检测结果获取两类接口。

    • 在线实时检测接口是文本检测服务实时反垃圾引擎检测接口,该接口实时返回检测结果,产品可以根据该结果对数据进行初步过滤。

    • 离线检测结果获取接口返回文本检测服务离线反垃圾引擎检测结果及部分人工质检结果,产品可根据该结果做进一步数据过滤。

    以下是文本检测服务接口调用示意图:

    文本检测服务接口调用示意图

    1.2.接口返回状态说明

    根据发布的内容、发布者、ip、设备等信息来检测是否为需拦截内容。接口同步返回易盾内容安全服务实时反垃圾引擎检测结果,产品可以根据该结果对数据进行初步过滤。该接口返回结果状态分以下三种:

    • 不通过:表示是确认内容非法,产品可对数据做删除隐藏处理。

    • 嫌疑:表示该内容疑似非法,需内容安全云服务离线检测模块进一步确认处理,详询易盾技术支持。

    • 通过:表示云安全反垃圾云服务实时反垃圾引擎未识别为非法内容,产品对该类数据可以直接放过,发表成功。云安全反垃圾云服务离线检测模块也会对这些数据做进一步分析处理,详询易盾技术支持

    二、接入步骤

    2.1、获取安全凭证

    在调用Open API前,需要从【易盾官网控制台】查看secretId,secretKey,businessId,用于计算接口请求认证签名,见附录-签名生成算法

    2.2、测试联调

    根据下文给出的说明构造并发送请求,获取结果,查看结果是否符合预期响应。

    三、接口清单

    3.1 文本实时检测接口

    3.1.1 接口用途

    提交需要检测的文本并返回检测结果,业务方可根据结果对数据进行初步过滤

    3.1.2 接入须知

    • 注意:单次请求<1万字符,字段长度超过1万字符,会截取前面1万字符进行检测和存储;

    3.1.3 使用形式

    • 接口地址:http://as.dun.163.com/v4/text/check

    • 请求方法:POST

    • 请求头:Content-Type:application/x-www-form-urlencoded

    3.1.4 请求参数

    • 请求参数:包括公共参数,基本参数和业务扩展参数
      • 公共参数
    名称 类型 是否必选 最大长度 描述
    secretId String Y 32 产品秘钥 id ,由易盾内容安全服务分配,产品标识
    businessId String Y 32 业务id ,由易盾内容安全服务分配,业务标识
    timestamp Number Y 13 请求当前 UNIX 时间戳,请注意服务器时间是否同步
    nonce Number Y 11 随机整数,与 timestamp 联合起来,用于防止重放攻击
    signatureMethod String N 指定传参 指定签名算法,国密:SM3,如果使用md5默认签名算法,可以不传
    signature String Y 32 请求签名,用来验证此次请求的合法性,具体算法见 签名生成算法
    • 基本参数
    参数名称 类型 是否必选 最大长度 描述
    dataId String Y 128 数据唯一标识,能够根据该值定位到该条数据,如对数据结果有异议,可以发送该值给客户经理查询
    content String Y 10000 用户发表内容,建议对内容中JSON、表情符、HTML标签、UBB标签等做过滤,只传递纯文本,以减少误判概率
    title String N 512 内容标题,适用于贴子、博客的文章标题等场景,建议抄送,辅助机审策略精准调优
    dataType Number N 4 子数据类型,与易盾内容安全服务约定即可
    version String Y 4 接口版本号,可选值 v4
    callback String N 2^16-1 数据回调参数,调用方根据业务情况自行设计,此该字段应该设计为能唯一定位到该次请求的数据结构,如对用户的昵称进行检测,dataId可设为用户标识(用户ID),用户修改多次,每次请求数据的dataId可能一致,但是callback参数可以设计成定位该次请求的数据结构,比如callback字段设计成json,包含dataId和请求的时间戳等信息,当然如果不想做区分,也可以直接把callback设置成dataId的值。
    publishTime Number N 13 发表时间,UNIX 时间戳(毫秒值)
    callbackUrl String N 256 人工审核结果回调通知到客户的URL。主动回调数据接口超时时间设置为2s,为了保证顺利接收数据,需保证接收接口性能稳定并且保证幂等性。
    checkLabels String N 512 业务过检分类,如果没有勾选分类提交返回参数错误,您可指定多个垃圾类别进行机器检测,多个垃圾类别以逗号分隔("100,200"),指定后业务配置过检分类即失效,过检分类列表:100:色情,200:广告,260:广告法,300:暴恐,400:违禁,500:涉政,600:谩骂,700:灌水,900:其他,1100:涉价值观
    category String N 128 来源,用于展示渠道名称,应用名称等
    • 业务扩展参数 业务扩展参数,有助于通过业务维度辅助反垃圾结果判定
    参数名称 类型 是否必选 最大长度 描述
    用户信息 - N - 用户信息包含账号、昵称、等级、角色等,请查看 业务扩展参数—用户信息
    设备信息 - N - 设备信息包含设备ID、设备ID类型等,请查看 业务扩展参数—设备信息
    场景信息 - N - 场景信息包含私聊、群聊、直播、帖子等场景字段,请查看 业务扩展参数—场景信息
    ip String N 128 用户IP地址,建议抄送,辅助机审策略精准调优
    relatedKeys String N 512 String数组,多个关联Key以逗号分隔("xxx,xxx"),最多三个Key,单个Key长度不超过128,适用于私聊/评论/跟帖等情况同一用户或不同用户发送多条违规内容关联检测的场景。如需要检测同一评论下的同一用户或不同用户发送违规内容盖楼场景,Key传值方式可以为("评论ID,用户ID")
    extStr1 String N 128 自定义扩展参数
    extStr2 String N 128 自定义扩展参数
    extLon1 Long N 2^63-1 自定义扩展参数
    extLon2 Long N 2^63-1 自定义扩展参数

    3.1.5请求参数示例(包括公共参数):

    {
        "secretId":"suwijdiwjsuzj1236547854sjwushaw",
        "businessId":"3",
        "timestamp":"1619692564000",
        "nonce":"siajdjwhsu11",
        "signature":"i9jes854erokjnmderjisiderjuijhhh",
        "dataId":"ywuaad",
        "content":"被检测文本",
        "version":"v4"
    }
    

    3.1.6 响应结果

    • 响应通用字段
    参数名称 类型 描述
    code Number 接口调用状态,200:正常,其他值:调用出错,返回码见附录-响应码
    msg String 结果说明,如果接口调用出错,那么返回错误描述,成功返回 ok
    result 数组 接口返回结果,各个接口自定义,若为空标识返回正常
    • result数据结构
    参数名称 类型 描述
    antispam json对象 图片反垃圾检测结果
    anticheat json对象 反作弊检测结果,如有需要请联系您的专属商务,未开通状态下此数组返回为空
    emotionAnalysis json对象 情感分析检测结果,如有需要请联系您的专属商务,未开通状态下此数组返回为空
    • 反垃圾结果
    参数名称 类型 描述
    action Number 检测结果,0:通过,1:嫌疑,2:不通过
    censorType Number 审核模式,0:纯机审,1:机审+部分人审,2:机审+全量人审
    strategyVersion String 策略版本号,策略更新时该参数会更新,可用于追溯策略调优效果
    taskId String 本次请求数据标识,可以根据该标识查询数据最新结果
    lang json数组 语种代码数组,详见 附录-语种代码表
    isRelatedHit boolean 是否关联检测命中,true:关联检测命中,flase:原文命中
    labels json数组 分类信息
    • labels 数据结构
    参数名称 类型 描述
    label Number 分类信息,100:色情,200:广告,260:广告法,300:暴恐,400:违禁,500:涉政,600:谩骂,700:灌水,900:其他,1100:涉价值观
    subLabels json数组 细分类信息,可能包含多个,可能为空
    level Number 分类级别,0:通过, 1:嫌疑,2:不通过
    details json对象 其他信息
    • subLabels 数据结构

    注意:易盾支持subLabel自定义细分类过检并返回,如有需求,可联系您的专属安全策略经理添加。

    参数名称 类型 描述
    subLabel Number 细分类,详细编码请参考下方对应细分类编码对应表
    • details 数据结构
    参数名称 类型 描述
    hint json数组 线索信息,用于定位文本中有问题的部分,辅助人工审核
    hitInfos json数组 线索详细信息
    • hitInfos 数据结构
    参数名称 类型 描述
    hitType Number 线索分类信息,返回10:表示命中用户自定义添加用户名单,返回11:表示命中用户自定义添加ip名单,返回30:表示命中用户自定义添加敏感词,返回140:标识命中反作弊(hitReason为反作弊命中原因,1:数据异常 2:行为模型 3:设备模型 4:业务类型 5:校验异常 6:模拟器 7:越狱或root 8:浏览器异常 9:ip异常 10:易盾黑名单 11:自定义黑名单 12:自定义白名单)
    hitClues String hitTyp命中30自定义添加敏感词,返回命中的自定义敏感词内容,如果没有命中hitType:30,则不返回该字段
    • 情感分析结果 emotionAnalysis 数据结构
    参数名称 类型 描述
    taskId String 本次请求数据标识,可以根据该标识查询数据最新结果
    sentiment String negative(负向情绪),neutral(中性情绪),positive(正向情绪),unknown(未知)
    positiveProb Number 0~1,代表正向情绪倾向,分数越高,正向情绪越高
    negativeProb number 0~1,代表负向情绪倾向,分数越高,负向情绪越高
    • 反作弊结果anticheat 数据结构
    参数名称 类型 描述
    taskId String 本次请求数据标识,可以根据该标识查询数据最新结果
    action Number 检测结果,0:通过,10:嫌疑,20:不通过
    hitInfos List 命中信息,例如:[{"hitType":5,"hitMsg":"无SDK数据"}],其中hitType类型为int,含义是命中类型,详见 hitType返回码及含义表 ,hitMsg类型为String,含义是命中详情,可定制返回值。

    3.1.7 响应结果示例

    结果为不通过时,输出示例如下

    {
      "code": 200,
      "msg": "ok",
      "result":{
        "antispam": {
          "taskId": "fx6sxdcd89fvbvg4967b4787d78a",
          "action": 1,
          "censorType": 0,
          "lang": ["en","vi"],
          "isRelatedHit":false,
          "labels": [
           {
            "label": 100,
            "level": 1,
            "details": {
              "hint": [
                "xxx,ooo"
              ],
              "hitInfos": []
            },
            "subLabels": [
              {
                "subLabel": "100002"
              }
             ]
           }
         ]
        },
    	"emotionAnalysis":{
    		"taskId":"fx6sxdcd89fvbvg4967b4787d78a",
    		"sentiment":"positive",
    		"positiveProb":0.95,
    		"negativeProb":0.05
    	},
    	"anticheat":{
    		    "taskId":"fx6sxdcd89fvbvg4967b4787d78a",
    		    "action":0,
    		    "hitInfos":[
    		    {
    		    "hitType":0
    		    }
    		   ]
    	}
     }
    } 
    

    结果为通过时,输出示例如下

    {
    	"code": 200,
    	"msg": "ok",
    	"result":{
    		"antispam": {
    			"taskId": "079560a6c9f34783bdce47e168510038",
    			"action": 0,
    			"labels": []
    		},
    		"emotionAnalysis":{
    		   "taskId":"fx6sxdcd89fvbvg4967b4787d78a",
    		   "sentiment":"positive",
    		   "positiveProb":0.95,
    		   "negativeProb":0.05
    		},
    		"anticheat":{
    		    "taskId":"fx6sxdcd89fvbvg4967b4787d78a",
    		    "action":0,
    		    "hitInfos":[
    		    {
    		    "hitType":0
    		    }
    		    ]
    		}
    	}
    }
    

    附录

    代码demo示例

    https://github.com/yidun/antispam-java-demo

    响应码定义

    状态码 返回信息 说明
    200 OK 接口调用成功
    400 BAD_REQUEST 请求缺少 secretId 或 businessId
    401 forbidden businessId无效或过期,请按照如下步骤排查:(1)试用时间为7天,试用到期请联系商务 (2)检测业务Id是否正确 (3)检测密钥信息是否正确 (4)检测请求接口是否匹配
    405 param error 请求参数异常,请检查参数是否有缺失,参数是否正确,如果检查无误请您及时联系我们。
    410 signature failure 签名验证失败,目前请求参数仅支持form表单形式,建议content-type设置为 application/x-www-form-urlencoded 编码格式
    411 high frequency 请求频率超过限制(QPS,文本默认200条/s,图片64张/s,视频直播100路/s,视频点播30路/s,直播电视墙100路/s,直播音频100路/s,点播音频30路/s)
    413 trial check amount over limit 试用期请求数据总量超过限制(试用期间,文本上限8W,图片上限5W,视频直播/点播上限500路,直播/点播电视墙上限100路,直播/点播音频上限500路)
    414 param len over limit 请求长度/大小超过限制
    415 target version limit 业务版本限制
    420 request expired 请求过期
    430 replay attack 重放攻击
    503 service unavailable 接口异常

    签名生成算法

    易盾内容安全服务使用签名方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature 参数),以验证用户身份,防止信息被恶意篡改。

    (1) 申请安全凭证

    在第一次使用 API 之前,需申请安全凭证,安全凭证包括 SecretId 和 SecretKey ,SecretId 是用于标识 API 调用者的身份,SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。SecretKey 必须严格保管,避免泄露。

    (2) 生成签名参数signature

    • 步骤一:对所有请求参数(包括公有参数和私有参数,但不包括 signature 参数),按照参数名ASCII码表升序顺序排序。如:foo=1, bar=2, foo_bar=3, baz=4 排序后的顺序是 bar=2, baz=4, foo=1, foobar=3。

    • 步骤二:将排序好的参数名和参数值构造成字符串,格式为:key1+value1+key2+value2… 。根据上面的示例得到的构造结果为:bar2baz4foo1foobar3 。

    • 步骤三:选择与 secretId 配对的 secretKey ,加到上一步构造好的参数字符串之后,如 secretKey=6308afb129ea00301bd7c79621d07591 ,则最后的参数字符串为 bar2baz4foo1foobar36308afb129ea00301bd7c79621d07591。

    • 步骤四:把步骤三拼装好的字符串采用utf-8编码,使用 MD5 算法对字符串进行摘要,计算得到 signature 参数值,将其加入到接口请求参数中即可。MD5 是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32位十六进制字符。

    • 代码示例

    /**
     * 生成签名信息
     * @param secretKey 产品私钥
     * @param params 接口请求参数名和参数值map,不包括signature参数名
     * @return
     */
    public static String genSignature(String secretKey, Map<String, String> params){
        // 1. 参数名按照ASCII码表升序排序
        String[] keys = params.keySet().toArray(new String[0]);
        Arrays.sort(keys);
    
        // 2. 按照排序拼接参数名与参数值
        StringBuilder sb = new StringBuilder();
        for (String key : keys) {
            sb.append(key).append(params.get(key));
        }
        // 3. 将secretKey拼接到最后
        sb.append(secretKey);
    
        // 4. MD5是128位长度的摘要算法,转换为十六进制之后长度为32字符
        return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
    }
    

    响应返回码

    响应返回码(code)反应了易盾内容安全云服务 API 调用和执行的概要结果。当返回码不为 200 时, 表示请求未正常执行,返回码描述 (msg) 对该结果进行了细化补充,用户可根据返回码判断 API 的执行情况。

    所有接口调用返回值均包含 code 和 msg 字段, code 为返回码值,msg 为返回码描述信息,返回码表如下:

    返回码 返回码描述 说明
    200 ok 接口调用成功
    400 bad request 请求缺少 secretId 或 businessId
    401 forbidden businessId无效或过期,请按照如下步骤排查:(1)试用时间为7天,试用到期请联系商务 (2)检测业务Id是否正确 (3)检测密钥信息是否正确 (4)检测请求接口是否匹配
    405 param error 请求参数异常,请检查参数是否有缺失,参数是否正确,如果检查无误请您及时联系我们。
    410 signature failure 签名验证失败,目前请求参数仅支持form表单形式,建议content-type设置为 application/x-www-form-urlencoded 编码格式
    411 high frequency 请求频率超过限制(QPS,文本默认200条/s,图片64张/s,视频直播100路/s,视频点播30路/s,直播电视墙100路/s,直播音频100路/s,点播音频30路/s)
    413 trial check amount over limit 试用期请求数据总量超过限制(试用期间,文本上限8W,图片上限5W,视频直播/点播上限500路,直播/点播电视墙上限100路,直播/点播音频上限500路)
    414 param len over limit 请求长度/大小超过限制
    415 target version limit 业务版本限制
    420 request expired 请求过期
    430 replay attack 重放攻击
    503 service unavailable 接口异常

    业务扩展参数

    按用户、设备、场景传入业务扩展参数,辅助反垃圾结果判定

    用户扩展参数

    根据用户信息输出用户画像,并与易盾自有画像库比对,辅助反垃圾结果判定

    参数名称 类型 是否必选 最大长度 描述
    account String N 128 用户唯一标识,与易盾账号画像库匹配,建议抄送,辅助机审策略精准调优
    phone string N 64 手机号,与易盾风险库匹配。默认国内手机号,如有海外手机,需包含国家地区代码,格式为“+447410xxx186(+44即为国家码)”。如果需要加密,支持传入hash值,hash算法:md5(phone)
    nickname String N 128 用户昵称,建议抄送,辅助机审策略精准调优
    gender Number N 4 用户性别,0未知,1男,2女,在社交、直播场景建议抄送,辅助策略精准调优
    age Number N 4 用户年龄,0未知,在社交场景建议抄送,辅助策略精准调优
    level Number N 4 用户等级,0未知,1初级,2中级,3高级,其他值请与易盾策略约定,建议抄送,辅助策略精准调优
    registerTime Number N 13 注册时间,UNIX 时间戳(毫秒值)
    friendNum Number N 20 好友数,在社交、直播场景中使用,建议抄送
    fansNum Number N 20 粉丝数,在社交、直播场景中使用,建议抄送
    isPremiumUse Number N 4 是否付费用户,0为默认值,1为付费,建议抄送,易盾将结合该信息综合判断
    role string N 32 用户类型角色,可针对不同的角色配置不同的策略。角色与易盾策略约定即可

    设备扩展参数

    根据设备信息输出设备画像,并与易盾自有设备画像库比对,辅助反垃圾结果判定

    参数名称 类型 是否必选 最大长度 描述
    deviceId String N 128 用户设备 id,与易盾设备画像库匹配,明文请转大写传入;MD5加密请明文转大写后MD5计算,再转大写传入,建议抄送
    deviceType Number N 4 用户设备id的类型,0:其他,10:IMEI,11:AndroidID,12:IDFA,13:IDFV,14:MAC ,20:IMEI_MD5,21:AndroidID_MD5,22:IDFA_MD5,23:IDFV_MD5,24:MAC_MD5
    mac String N 64 用户设备mac信息,与易盾设备画像库匹配,建议抄送
    imei String N 64 国际移动设备识别码,与易盾设备画像库匹配,建议抄送
    idfa String N 64 iOS设备标识码,与易盾设备画像库匹配,建议抄送
    idfv String N 64 iOS设备标识码 ,与易盾设备画像库匹配,建议抄送
    appVersion String N 32 APP版本号 ,可根据不同版本号配置不同策略,建议抄送

    场景扩展参数

    场景扩展参数,有助于通过业务场景维度辅助反垃圾结果判定

    参数名称 类型 是否必选 最大长度 描述
    receiveUid String N 64 接受消息的用户标识,私聊/评论回复场景使用,易盾可根据该id关联检测,辅助机审策略精准调优
    relationship int N 11 收发消息者好友关系,1接收人关注发送人,2发送人关注接收人,3互相关注,4互未关注,私聊/评论场景抄送
    groupId String N 32 群聊id,群聊场景使用,建议抄送,辅助机审策略精准调优
    roomId String N 32 聊天室/直播/游戏房间,派对房/直播场景使用,可根据不同的房间设置不同策略,建议抄送,辅助机审策略精准调优
    topic String N 128 文章/帖子id,发帖/动态场景使用,易盾可根据该id,关联检测,辅助机审策略精准调优
    commentId String N 32 主评论id,围绕主评论盖楼场景使用,建议抄送,辅助机审策略精准调优
    commodityId String N 32 商品id,直播卖货/商品介绍场景使用,可根据商品类型设置策略,建议抄送,辅助机审策略精准调优

    文本subLabel细分类编码对照表

    一级分类 二级分类 描述
    100 100001 色情其他
    100 100002 色情传播
    100 100003 色情性器官
    100 100004 色情挑逗
    100 100005 色情低俗段子
    100 100006 色情性行为
    100 100007 色情舆情事件
    100 100008 色情交友类
    200 200009 商业推广
    200 200011 刷量行为
    200 200012 广告其他
    200 200010 广告法
    260 260052 广告法-涉医疗用语(非药品禁止宣传药效)
    260 260053 广告法-迷信用语
    260 260054 广告法-需要凭证(可以写但需要凭证证明)
    260 260055 广告法-限时性用语(可以写但必须有具体时间)
    260 260056 广告法-涉嫌诱导消费者
    260 260057 广告法-涉嫌欺诈消费者
    260 260058 广告法-法律风险较高
    260 260059 广告法-极限词(用语绝对化)
    300 300016 暴恐其他
    400 400017 违禁其他
    400 400021 违禁网监要求
    500 500013 涉政其他
    500 500070 核心领导人
    500 500014 敏感专项
    500 500015 严格涉政
    500 500039 时事报道
    500 500040 领导人相关
    500 500041 英雄烈士相关
    500 500042 邪教迷信
    500 500043 落马官员相关
    500 500044 热点舆情
    500 500045 涉政综合
    600 600018 谩骂其他
    700 700019 灌水其他
    900 900020 其他
    1100 1100102 宣扬拜金炫富
    1100 1100103 宣扬浪费粮食(吃播)
    1100 1100106 教唆自杀自残
    1100 1100101 涉价值观其他
    1100 1100104 宣扬涉黑文化
    1100 1100105 宣扬腐文化
    1100 1100107 封建迷信
    Online Chat Tel:95163223