反外挂嫌疑明细数据查询
2024.03.14 20:19:08
接口用途
提供嫌疑数据明细查询服务,返回结果包括异常数据,不包括正常数据。
主要用于异常数据同步:从易盾拉取数据场景,以固定时间窗口拉取异常数据。例如,每次查询1分钟前的数据,时间跨度也是1分钟,则可以按1分钟时间窗口,周期性滑动拉取数据。
接入须知
-
注意事项:因取证信息场景复杂,为了保障封号依据完备,如需封号,建议结合角色的业务数据进行二次判断或者 和易盾技术人员进行二次确认,以确保准确无误;控制接口调用频率,频率过高,可能会超过频率限制,导致查询失败,建议间隔大于10s。
-
数据时间有效性
- 可以导出最近一个月的所有数据
- 可以导出Open API接入之前的数据
-
导出数据量
- 采用深度分页方式返回数据:如果查询条件返回数据量超过1万条,会以分页形式返回;下一页查询标识,见
startFlag
请求参数说明 - 建议每次查询1分钟前的数据,时间跨度也是1分钟,按1分钟时间窗口,周期性滑动拉取数据。这个时间粒度,很少会超过1万条。
- 支持去重导出。在查询时间范围内,如果以下字段内容都相同时,仅会返回一条记录。字段如下:
appId,deviceId,roleId,roleName,roleAccount,plugRisk,plugType,envRisk,envType,otherRisk,otherType
。字段解释,见接口响应说明
- 采用深度分页方式返回数据:如果查询条件返回数据量超过1万条,会以分页形式返回;下一页查询标识,见
-
数据返回格式
- 有两种: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格式。
名称 | 类型 | 描述 |
---|---|---|
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数据结构 |
名称 | 类型 | 描述 |
---|---|---|
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
}