接口用途

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

主要用于异常数据同步：从易盾拉取数据场景，以固定时间窗口拉取异常数据。例如，每次查询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 
}