一、接入说明

易盾端游智能反外挂服务，对外提供Open API接口服务，如下：

• 反外挂数据服务
  • 反外挂嫌疑在线检测
  • 按玩家信息条件查询反外挂详情接口
  • 根据时间段批量查询反外挂详情接口
  • 资源文件数据上传

二、接入步骤

2.1、获取安全凭证

在调用Open API服务接口之前，需要从【易盾官网-服务管理-已开通业务】获取AppId和AppKey，用于计算接口请求认证签名，见认证参数token生成说明。

2.2、测试联调

• 从客户端发送数据，验证对应Open API接口响应数据

三、接口清单

3.1、接口通用说明

• 传输协议：支持Http和Https协议

• 请求方法：默认为POST

• 字符编码：请求参数与响应数据，统一为UTF-8编码

• 请求API结构说明

  • 请求API符合Http请求规范，由三部分组成：请求Header，请求URL，请求Body。
  • 请求的Body数据，分为公共参数，和API私有参数。

名称	组成	描述	备注
请求URL-域名	域名	例如http://open-yb.dun.163.com	线上域名
请求URL-路径	路径Path	例如/api/open/v1/risk/detail_data/list	API路径
请求Header	Content-Type：application/json	参数格式	请求参数为JSON格式
请求Body	公共请求参数	参数说明见下文	公共请求参数，用于标识产品，及接口调用认证。在每个接口单独的接口文档中不再对这些参数进行说明，每次请求均需要携带这些参数
请求Body	接口私有参数	详见每个接口定义描述	每个接口特有参数，

• 公共请求参数

名称	类型	是否必填	描述
appId	String	是	每个应用接入时，会分配AppID，和对应密钥AppKey。从【易盾官网-服务管理-已开通业务】页面获取。
timestamp	Long	是	调用接口当前时间，单位毫秒，防止重放
nonce	String	是	随机码，防止重放
token	String	是	使用appKey签名的数据，校验权限，生成方式，见附录 认证参数token生成说明。

• 请求Body参数示例

{
  "appId":"xxx8888949",
  "timestamp":"${currentTime}",
  "token":"${sign}",
  "nonce":"111",
  "beginDateTime":1564041324000,
  "endDateTime":1574127724519,
  "roleId": "00992755211_11",
  "deviceId": "", 
  "userAccount": "",
  "roleName": ""
}

• 响应数据结构说明

大部分接口响应数据，是JSON格式，描述如下：

名称	类型	描述
code	Integer	响应码，正常情况时为200，异常时，见附录 响应码定义
msg	String	响应码说明，正常时返回ok，异常时，见附录 响应码定义
data	JSONObject或Array	返回数据

3.2 反外挂嫌疑在线检测

3.2.1 接口用途

本接口用于反外挂嫌疑数据在线检测。

3.2.2 接入须知

注意事项：因取证信息场景复杂，为了保障封号依据完备，如需封号，建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认，以确保准确无误

3.2.3 使用形式

• 接口地址：http://open-yb.dun.163.com/api/open/v1/nep/doubtful/check

• 请求方法：POST

• 请求头：Content-Type：application/json

3.2.4 请求参数

• 请求参数：包括公共参数，和接口参数
  • 见公共请求参数
  • 接口参数如下：

名称	类型	是否必填	描述
mrData	String	是	嫌疑上报数据，游戏方需要从反外挂客户端SDK获取该数据。查看反外挂客户端SDK接入文档，请联系易盾获取。
ip	String	否	玩家的IP
roleId	String	否	角色ID
roleName	String	否	角色名称
roleServer	String	否	服务器
extData	String	否	额外信息，游戏方可以自己构建json结构，最大长度：2048

3.2.5 请求参数示例（包括公共参数）：

{
   "appId": "xxx8888888",
    "timestamp": "${currentTime}",
    "nonce": "1111111",
    "token": "${sign}",
    "mrData":  "xxxxxxx",
    "ip":  "1.1.1.1",
    "roleId":  "yyyyyyy",
    "roleName":  "yyyyyyy",
    "roleServer":  "yyyyyyy",
    "extData": "zzzzzzz"
}

3.2.6 响应结果

响应数据格式：JSON

• 响应头为：Content-Type：application/json

参数名称	类型	描述
code	Integer	响应码，正常情况时为200，异常时，见附录 响应码定义
msg	String	响应码说明，正常时返回ok，异常时，见附录 响应码定义
data	Object	返回数据，格式见【检测结果的数据格式】

• 检测结果的数据格式:

名称	类型	描述
action	Integer	建议执行动作：0 正常(放行)，10 异常(闪退)
hitInfos	List	命中风险信息，例如：[{"tag1Id":"一级Id","tag1Name":"一级名称","tag2Id":"二级Id","tag2Name":"二级名称","tag3Id":"三级Id","tag3Name":"三级名称"}]， 其中, tag1Id类型为String，含义是命中一级输出标识Id， tag1Name类型为String，含义是命中一级输出标识名称； tag2Id类型为String，含义是命中二级输出标识Id， tag2Name类型为String，含义是命中二级输出标识名称； tag3Id类型为String，含义是命中三级输出标识Id， tag3Name类型为String，含义是命中三级输出标识名称； 如果同时命中多个类型，则会返回所有风险信息

3.2.7响应结果示例：

• 嫌疑数据识别为正常的响应结果：

{
  "code": 200,
   "msg": "ok!",
   "data": {
       "action": 0,
       "hitInfos": null        
  }
  
}

• 嫌疑数据识别为异常的响应结果：

{

  "code": 200,
  "msg":"ok!",
  "data": {
      "action": 10,
       "hitInfos": [
           {"tag1Id":"一级Id","tag1Name":"一级名称","tag2Id":"二级Id","tag2Name":"二级名称","tag3Id":"三级Id","tag3Name":"三级名称"}
       ]
  }
}

注意:

• 当返回无数据时，数据处理可能存在延时或者数据不存在。
• 自动封禁有风险，操作请谨慎，建议综合参考其它因素。

3.3 按玩家信息条件查询反外挂详情接口

3.3.1 接口用途

本接口用于按玩家信息条件查询反外挂详情。

3.3.2 接入须知

注意事项：因取证信息场景复杂，为了保障封号依据完备，如需封号，建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认，以确保准确无误

3.3.3 使用形式

• 接口地址：http://open-yb.163yun.com/api/open/v1/pc/list

• 请求方法：POST

• 请求头：Content-Type：application/json

3.3.4 请求参数

• 请求参数：包括公共参数，和接口参数

  • 见公共请求参数

  • 接口参数如下：

名称	类型	是否必填	描述
deviceId	String	否	设备Id
roleId	String	否	角色Id
roleName	String	否	角色名称
userAccount	String	否	用户账号
beginDateTime	Long	是	查询开始时间 ，单位毫秒（只支持最近一个月）
endDateTime	Long	否	查询结束时间（不包含），单位毫秒（结束时间-开始时间<24小时，不填写默认开始时间加24小时)

注意事项：

1）接口参数deviceId、roleId、roleName、userAccount 在查询条件中，至少选填一个

2）控制接口调用频率，频率过高，可能会超过频率限制，导致查询失败,建议间隔大于10s

3.3.5 请求参数示例（包括公共参数）：

{
	"appId":"W009887949",
	"timestamp":"${currentTime}",
	"token":"${sign}",
	"nonce":"111",
	"beginDateTime":1564041324000,
	"endDateTime":1574127724519,
	"roleId":"00992755211_11", 
	"deviceId": "",
	"userAccount": "",
	"roleName": ""
}

3.3.6 响应结果

响应数据格式：JSON

• 响应头为：Content-Type：application/json

参数名称	类型	描述
code	Integer	响应码，正常情况时为200，异常时，见附录 响应码定义
msg	String	响应码说明，正常时返回ok，异常时，见附录 响应码定义
data	Array[RiskData]	返回数据，RiskData类型结构如下

• RiskData类型结构:

名称	类型	描述
createTime	Long	入库时间
deviceId	String	设备Id
envDetection	Array	环境检测结果
featureContent	String	证据内容
featureDesc	String	证据描述
level	Integer	玩家游戏等级
mac	String	MAC地址
matchRuleName	Array	命中规则名称
plugs	Array	外挂检测结果
riskDetection	Array	风险检测结果
roleId	String	角色ID
roleName	String	角色名称
serverId	Integer	服务器ID
serverName	String	服务器名称
userAccount	String	游戏账号
clientVersion	String	客户端版本
defenseResult	String	防御结果
ip	String	客户端IP
trans	String	传输方式

3.3.7响应结果示例：

• 正常的响应结果：

{
  "code":200,
  "data":[
      {
          "createTime":1602673073516,
          "deviceId":"330022551144889914",
          "envDetection":[
              "yl应用环境A三级-PCHJ.yl.S2"
          ],
          "featureContent":"22112233445566778899002233445511",
          "featureDesc":"lua提取修改器.exe",
          "level":89,
          "mac":"00:05:28:90:80:00:1e",
          "matchRuleName":[
              "yl应用规则PC-S",
              "yl风险规则PC-S"
          ],
          "plugs":[
              "yl外挂A-PCWG.yl.T1"
          ],
          "riskDetection":[
              "yl风险二级-PCFX.yl.S2"
          ],
          "roleId":"00992755211_11",
          "roleName":"全能骑士-DT",
          "serverId":10086,
          "serverName":"军团-DT",
        "userAccount":"ylTestxxx@126.com",
        "clientVersion":"10010",
        "ip":"127.0.0.1",
        "defenseResult":"拦截成功",
        "trans":"客户端直传"
      }
  ],
  "msg":"ok"
}

• 异常的响应结果：

{
  "code":4401,
  "msg":"Token验证失败"
}

3.4 根据时间段批量查询反外挂详情接口

3.4.1 接口用途

本接口用于根据时间段批量查询反外挂详情。

3.4.2 接入须知

注意事项：因取证信息场景复杂，为了保障封号依据完备，如需封号，建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认，以确保准确无误

3.4.3 使用形式

• 接口地址：http://open-yb.163yun.com/api/open/v1/pc/batchQuery

• 请求方法：POST

• 请求头：Content-Type：application/json

3.4.4 请求参数

• 请求参数：包括公共参数，和接口参数
  • 见公共请求参数
  • 接口参数如下：

名称	类型	是否必填	描述
nextFlag	array	否	1. 第一次查询时，该字段填充null或者"" 2. 当某个查询条件返回数据大于5000条，则需要分批返回数据，表示下一批数据起始标记。3. 当nextFlag数组返回为空时，表示数据都已经返回，不需要继续执行下一批查询
beginDateTime	long	是	查询开始时间 ，单位毫秒（只支持最近一个月）
endDateTime	long	否	查询结束时间（不包含），单位毫秒（结束时间-开始时间<24小时，不填写默认开始时间加24小时)

注意事项：

当某个查询条件返回数据大于5000条，需要保持beginDateTime、endDateTime查询条件不变，更新nextFlag值获得剩余的数据

3.4.5 请求参数示例（包括公共参数）：

{
	"appId":"W009887949",
	"timestamp":"${currentTime}",
	"token":"${sign}",
	"nonce":"111",
	"beginDateTime":1606701600000,
	"endDateTime":1606730400000,
	"nextFlag":[1606717845085, "2020-11-30-ff5fccf4516c1e7a19bd61d8dff6a246"]
}

3.4.6 响应结果

响应数据格式：JSON

• 响应头为：Content-Type：application/json

参数名称	类型	描述
code	Integer	响应码，正常情况时为200，异常时，见附录 响应码定义
msg	String	响应码说明，正常时返回ok，异常时，见附录 响应码定义
data	Object	返回数据，格式见【结果的数据格式】

• Data的数据样例

  {
  	"nextFlag":[1602642310996, "2020-10-14-7eddcf0facecda658b92e0a44dfa76e3"],
  	"total":100004,
  	"pcData":[]
  }
  

  nextFlag：如果total大于5000条，则会返回nextFlag，下一次查询需要附带上次查询返回的

  nextFlag。当 nextFlag 返回 [ ] ，代表所有符合条件数据已经查询完毕。

  total：符合查询条件的数据总量

  pcData：查询返回的具体数据。字段解释如下：

• pcData数据格式

名称	类型	描述
createTime	Long	入库时间
deviceId	String	设备Id
envDetection	Array	环境检测结果
featureContent	String	证据内容
featureDesc	String	证据描述
level	Integer	玩家游戏等级
mac	Long	MAC地址
matchRuleName	Array	命中规则名称
plugs	Array	外挂检测结果
riskDetection	Array	风险检测结果
roleId	String	角色ID
roleName	String	角色名称
serverId	Integer	服务器ID
serverName	String	服务器名称
userAccount	String	游戏账号
clientVersion	String	客户端版本
defenseResult	String	防御结果
ip	String	客户端IP
trans	String	传输方式

3.4.7响应结果示例：

• 正常的响应结果：

{
  "code":200,
  "data":{
  "nextFlag":[1602642310996, "2020-10-14-7eddcf0facecda658b92e0a44dfa76e3"],
  "total":100004,
  "pcData":
  	[{
  	"createTime":1602673073516,
  	"deviceId":"330022551144889914",
  	"envDetection":["yl应用环境A三级-PCHJ.yl.S2"],
  	"featureContent":"22112233445566778899002233445511",
  	"featureDesc":"lua提取修改器.exe",
  	"level":89,
  	"mac":"00:05:28:90:80:00:1e",
  	"matchRuleName":["yl应用规则PC-S","yl风险规则PC-S"],
  	"plugs":["yl外挂A-PCWG.yl.T1"],
  	"riskDetection":["yl风险二级-PCFX.yl.S2"],
  	"roleId":"00992755211_11",
  	"roleName":"全能骑士-DT",
  	"serverId":10086,
  	"serverName":"军团-DT",
  	"userAccount":"ylTestxxx@126.com",
  	"clientVersion":"10010",
  	"ip":"127.0.0.1",
  	"defenseResult":"拦截成功",
  	"trans":"客户端直传"}
  	]
  	},
  "msg":"ok"
}

• 异常的响应结果：

{
  "code":4401,
  "msg":"Token验证失败"
  }

3.5 资源文件数据上传

3.5.1 接口用途

本接口用于端游反外挂资源文件数据上传，目前仅支持图片文件上传。

3.5.2 接入须知

注意事项：因取证信息场景复杂，为了保障封号依据完备，如需封号，建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认，以确保准确无误

3.5.3 使用形式

• 接口地址：http://open-yb.dun.163.com/api/open/v1/nep/resources/upload

• 请求方法：POST

• 请求头：Content-Type：application/json

3.5.4 请求参数

• 请求参数：包括公共参数，和接口参数
  • 见公共请求参数
  • 接口参数如下：

名称	类型	是否必填	描述
mrData	String	是	上报资源文件数据，游戏方需要从反外挂客户端SDK获取该数据。查看反外挂客户端SDK接入文档，请联系易盾获取。
transMsgType	Integer	是	用于标识消息类型，图片文件数据为1，必传
ip	String	否	玩家的IP
extData	String	否	额外信息，游戏方可以自己构建json结构，最大长度：2048

3.5.5 请求参数示例（包括公共参数）：

{
   "appId": "xxx8888888",
    "timestamp": "${currentTime}",
    "nonce": "1111111",
    "token": "${sign}",
    "mrData":  "xxxxxxx",
    "transMsgType": 1,
    "ip":  "1.1.1.1",
    "extData": "zzzzzzz"
}

3.5.6 响应结果

响应数据格式：JSON

• 响应头为：Content-Type：application/json

参数名称	类型	描述
code	Integer	响应码，正常情况时为200，异常时，见附录 响应码定义
msg	String	响应码说明，正常时返回ok，异常时，见附录 响应码定义
data	Object	返回数据，该接口无返回数据

3.5.7响应结果示例：

• 上传成功时的响应结果：

{
  "code": 200,
   "msg": "ok!"
  
}

• 上传失败时的响应结果（code值非200时均为上传失败）：

{

  "code": 400,
  "msg": "请求参数不合法!"
}

附录

响应码定义

状态码	说明
200	正常
400	请求参数不合法
401	未授权或者授权已过期
402	服务下线
403	无权限操作
404	服务不存在
405	长度超过限制
406	请求实体数据大小超过限制！
407	请求过期
411	请求频率或数量超过限制！
500	服务异常
501	操作失败
4001	查询时间超出跨度
4400	参数appId缺失
4401	Token验证失败
5503	API未开放，不可使用
5509	API QPS超出限制
5709	API 最小请求频率超出限制，需要降低请求频率
5710	App Key 不存在，或者已失效

认证参数token生成说明

接口使用签名方式进行认证，每一次请求都必须包含签名信息（即参数token），以验证用户身份，防止信息被恶意篡改。具体使用步骤如下。

(1) 申请安全凭证

使用 API 之前，从【易盾官网-服务管理-已开通业务】页面获取appId和appkey。请妥善保管，避免泄漏。

(2) 生成签名参数token

• 步骤一：将公共参数，按照参数名ASCII码表升序顺序排序。如参数：foo=1， bar=2，foo_bar=3， baz=4 。排序后的顺序是 bar=2， baz=4， foo=1， foobar=3。

• 步骤二：将排序好的参数名参数值对，拼装成字符串，格式为：key1value1key2value2…。根据上面示例结果为：bar2baz4foo1foobar3 。

• 步骤三：将安全凭证的appkey，加到上一步拼装的参数字符串之后。

• 步骤四：把步骤三的字符串，采用 UTF-8 编码，使用 MD5算法（128位长度）对字符串进行摘要计算，得到token参数值（32位十六进制字符串）。

• 代码示例

String token= SignatureUtils.genSignature(appKey, appId, timestamp, nonce);
其中：SignatureUtils.java 如下：

package com.netease.is.clientapi.utils;
import com.google.common.collect.Maps;
import org.apache.commons.codec.digest.DigestUtils;
import java.io.UnsupportedEncodingException;
import java.util.Arrays;
import java.util.Map;
/**
* Created by yubaohong on 19-5-22.
  */
  public class SignatureUtils {
     /**
     * 暴露获取token的方法
     * @param appKey
     * @param appId
     * @param timestamp
     * @param nonce
     * @return
     * @throws UnsupportedEncodingException
        */

      public static String genSignature(String appKey, String appId, String timestamp, String nonce) throws UnsupportedEncodingException {
        Map<String, String>userParams = getTokenParams(appId, timestamp, nonce);
        return SignatureUtils.genSignature(appKey, userParams);
      }

     /**
     * 生成签名信息
     * @param appKey产品私钥
     * @param params 接口请求参数名和参数值map，不包括signature参数名
     * @return
        */

      private static String genSignature(String appKey, Map<String, String> params) throws UnsupportedEncodingException {
        // 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. 将appKey拼接到最后
        sb.append(appKey);
        // 4. MD5是128位长度的摘要算法，转换为十六进制之后长度为32字符
        return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
      }

    /**
     * 拼接参数
     * @param appId
     * @param timestamp
     * @param nonce
     * @return
        */

      private static Map<String, String> getTokenParams(String appId, String timestamp, String nonce) {
        <String, String> userParams = Maps.newHashMap();
        userParams.put("appId", appId);// 固定
        userParams.put("timestamp", timestamp);
        userParams.put("nonce", nonce);
        return userParams;
      }
  }