反外挂嫌疑明细数据查询

2024.01.30 16:13:45

    接口用途

    提供嫌疑数据明细查询服务,返回结果包括异常数据,不包括正常数据。

    主要用于异常数据同步:从易盾拉取数据场景,以固定时间窗口拉取异常数据。例如,每次查询1分钟前的数据,时间跨度也是1分钟,则可以按1分钟时间窗口,周期性滑动拉取数据。

    接入须知

    • 注意事项:因取证信息场景复杂,为了保障封号依据完备,如需封号,建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认,以确保准确无误;控制接口调用频率,频率过高,可能会超过频率限制,导致查询失败,建议间隔大于10s。

    • 数据时间有效性

      • 可以导出最近一个月的所有数据
      • 可以导出Open API接入之前的数据
    • 导出数据量

      • 采用深度分页方式返回数据:如果查询条件返回数据量超过1万条,会以分页形式返回;下一页查询标识,见startFlag请求参数说明
      • 建议每次查询1分钟前的数据,时间跨度也是1分钟,按1分钟时间窗口,周期性滑动拉取数据。这个时间粒度,很少会超过1万条。
      • 支持去重导出。在查询时间范围内,如果以下字段内容都相同时,仅会返回一条记录。字段如下:appId,deviceId,roleId,roleName,roleAccount,plugRisk,plugType,envRisk,envType,otherRisk,otherType字段解释,见接口响应说明
    • 数据返回格式

      • 有两种:Json格式,LinedText分行文本格式
      • 对于查询返回数据量,经常大于1千条的,建议使用LinedText格式,反序列化性能优于Json格式。

    使用形式

    • 接口地址:http://open-yb.dun.163.com/api/open/v2/risk/detail_data/list
    • 旧版接口地址:http://open-yb.dun.163.com/api/open/v1/risk/detail_data/list
    • 请求方法:POST
    • 请求头:Content-Type:application/json
    • 旧版接口与新版接口差异说明:旧版接口(v1)与新版接口(v2)返回的嫌疑明细数据是相同的,新版接口仅仅对旧版接口返回的数据进行了外层封装,封装形式见响应公共字段。目前旧版接口已废弃,但仍继续维护,已经接入旧版接口的用户可继续正常使用,推荐使用新版接口。

    请求参数

    • 请求参数:包括公共参数,和接口参数
    名称 类型 是否必填 描述
    duplicate Integer 1:不去重查询;0:去重查询(默认)。去重查询是指,在查询时间范围内,如果以下字段内容都相同时,仅会返回一条记录。字段如下:appId,deviceId,roleId,roleName,roleAccount,plugRisk,plugType,envRisk,envType,otherRisk,otherType字段解释,见接口响应说明
    queryTimeType Integer 0: 使用客户端事件发生时间(默认); 1:使用入库时间
    beginDateTime Long 开始时间(包括),单位毫秒
    endDateTime Long 结束时间(包括),单位毫秒。默认为当前时间
    startFlag String 用于分页查询的关联标记。第一次查询时,该字段填充"",后续查询时,需要判断上一次查询的返回数据中startFlag值,如果startFlag不为null,表示需要分页查询。当使用分页查询时,startFlag字段使用上一次返回值填充,其他字段保持不变,继续调用查询接口。如果startFlag为null,例如返回数据为{"code": 200, "msg": "ok", "data": {"size": 100, "startFlag": null, "data": [{},...]}},表示不需要分页查询,可以使用新的时间条件查询。
    formatType Integer 0: 返回数据格式为LinedText格式; 1: 返回数据格式为JSON格式; 默认为0。
    roleId String 根据指定角色ID筛选
    roleIdList List 根据角色ID列表批量筛选
    account String 根据指定账号筛选
    accountList List 根据账号列表批量筛选
    ip String 根据指定IP筛选
    ipList List 根据IP列表批量筛选
    packageName String 根据指定包名/BundleId筛选
    appVersion String 根据指定APP版本号筛选
    thirdLevelTagName String 根据三级标签名称筛选
    thirdLevelTagNameList List 根据三级标签名称列表批量筛选
    dataType Integer 查询的数据类型,0:异常数据, 1:全部数据; 默认为0, 表示查询异常数据

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

    {"appId":"${APPID}",
    "timestamp":${currentTime},
    "token":"${sign}",
    "nonce":"111",
    "duplicate":1,
    "beginDateTime":1564041324000,
    "endDateTime":1574127724519,
    "startFlag":""
    "account":"xx",
    "roleId":"xx",
    "packageName":"xx",
    "appVersion":"xx",
    "ip":"xx.xx",
    "accountList":[],
    "roleIdList":[],
    "ipList":[],
    "thirdLevelTagName": "",
    "thirdLevelTagNameList": [],
    "dataType": 0
    }
    

    响应结果

    • 响应结果,支持两种格式:JSON与LinedText格式。
      • JSON格式,在返回几千条场景下,反序列化性能不如LinedText格式

      • LinedText格式,在大数据量场景下,反序列性能相对较好

      • 其中,每一条的嫌疑明细数据结构,如下

        • Doubt:嫌疑明细数据
    名称 类型 描述
    deviceId String 设备ID
    osVersion String iOS版本/IOS版本
    roleId String 角色ID
    roleAccount String 账号
    roleName String 角色名称
    roleServer String 服务器
    packageName String 包名/BundleId
    appVersion String APP版本号
    gameVersion String 游戏版本
    assetVersion String 资源版本
    ip String IP
    plugRisk String 外挂风险
    plugType String 外挂类型
    envRisk String 环境风险
    envType String 环境类型
    otherRisk String 其它风险
    otherType String 其它类型
    defenceResult String 风险处理
    createTime String 入库时间
    transType String 传输方式
    emulatorDeviceId String 模拟器设备ID
    signHash String 签名
    reflectSignMd5 String 签名MD5
    antiSdkVersion String 反外挂sdk版本
    cheatInfo1 String 取证信息,可能包含多条,以";"分割
    location String 地区
    protectionResult String 防护结果
    gameJson String 拓展信息
    JSON格式
    • 响应头为:Content-Type:application/json
    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见响应返回码
    msg String 响应码说明,正常时返回ok,异常时,见响应返回码
    data SuspectData 调用成功时会有该字段返回,该字段的数据结构,见SuspectData数据结构
    • SuspectData数据结构如下:
    名称 类型 描述
    size Integer 本次返回记录数
    startFlag String 用于分批查询的关联标记。1. 当查询需要分批返回数据时,表示下一批数据起始标记。2. 当为null值,表示数据都已经返回,不需要继续执行下一批查询
    data Array<Doubt> 具体返回数据,每条数据类型,见Doubt嫌疑明细数据结构
    LinedText格式(分行文本格式)
    • 响应头为:Content-type: text/plain;charset=utf-8
    • 数据以\n分行,每行的各个字段以\t键分隔
    • 从第一行,到第四行,用于描述数据信息。
    • 从第5行开始,为嫌疑数据记录,各个字段说明,见Doubt嫌疑明细数据结构
    • 格式样例
    每行数据内容格式 描述
    第1行 startFlag=${下一批数据起始标记} 1. 当查询需要分批返回数据时,表示下一批数据起始标记。2. 当为null值,表示数据都已经返回,不需要继续执行下一批查询
    第2行 separator=${列分隔符号} 行中的不同列之间分隔符,如Tab,或\001等
    第3行 colums=${数据列名称} 数据列名称,以"列分隔符"切分
    第4行 size=${总行数} 数据总行数,可以为空值
    第5行 每行数据记录 数据记录,从第5行开始,各个字段说明,见第3行列名
    第...行 ... ...

    响应结果示例

    JSON格式示例如下:
    {
        "code": 200,
        "msg": "ok",
        "data": {
            "size": 10000,
            "startFlag": "e9376eef25a34b47b84ff2e560992123",
            "data": [
                {
                    "deviceId": "deviceId02",
                    "osVersion": "7.0.1",
                    "roleId": "roleTestid02",
                    "roleAccount": "roleaccount007",
                    "roleName": "yltestRN",
                    "roleServer": "roleservern02",
                    "packageName": "com.xxxx.xxxx",
                    "appVersion": "1.1.1",
                    "gameVersion": "1.0.1",
                    "assetVersion": "0.1.1",
                    "ip": "10.xxx.xxx.xxx",
                    "plugRisk": "未发现",
                    "plugType": "",
                    "envRisk": "ROOT",
                    "envType": "",
                    "otherRisk": "正常",
                    "otherType": "",
                    "defenceResult": "拦截成功",
                    "createTime": "2021-04-28 14:38:44",
                    "transType": "客户端直传",
                    "emulatorDeviceId": "QAEmulatorDeviceid00",
                    "signHash": "3141041934",
                    "reflectSignMd5": "-",
                    "antiSdkVersion": "1.6.3",
                    "cheatInfo1": "xxx;xx",
                    "location": "中国-浙江杭州",
                    "protectionResult": "防护成功",
                    "gameJson": "{\"xxx\":\"xxx\"}"
    
                },
                {
                    "deviceId": "deviceId02",
                    "osVersion": "7.0.1",
                    "roleId": "roleTestid02",
                    "roleAccount": "roleaccount007",
                    "roleName": "yltestRN",
                    "roleServer": "roleservern02",
                    "packageName": "com.xxxx.xxxx",
                    "appVersion": "1.1.1",
                    "gameVersion": "1.0.1",
                    "assetVersion": "0.1.1",
                    "ip": "xxx.xxx.xxx.xxx",
                    "plugRisk": "未发现",
                    "plugType": "",
                    "envRisk": "ROOT",
                    "envType": "",
                    "otherRisk": "正常",
                    "otherType": "",
                    "defenceResult": "拦截成功",
                    "createTime": "2021-04-28 14:38:44",
                    "transType": "客户端直传",
                    "emulatorDeviceId": "QAEmulatorDeviceid00",
                    "signHash": "3141041934",
                    "reflectSignMd5": "-",
                    "antiSdkVersion": "1.6.3",
                    "cheatInfo1": "xxx;xx",
                    "location": "xxx",
    	            "protectionResult": "防护成功",
                    "gameJson": "{\"xxx\":\"xxx\"}"
                }
                  ]
        }
    }
    
    LinedText格式示例如下:

    异常返回的数据
    • 响应头为:Content-Type:application/json
    • 数据JSON格式如下
    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见响应返回码
    msg String 响应码说明,正常时返回ok,异常时,见响应返回码
    • 异常数据示例
    {  
        "msg": "未授权或者授权已过期",  
        "code": 401 
    } 
    
    Online Chat Tel:95163223 Free trial