数据查询接口V6
2024.11.14 16:59:44
接口说明
本接口的功能是智能风控明细数据查询，主要用于检测结果数据同步。接口支持根据指定时间窗口查询该时间段内的全部检测数据，支持分页查询，每页最多返回1万条。建议时间区间不要太大，尽量使用较小时间段遍历查询。例如如果想查最近一个小时的数据，可按1分钟的时间段进行遍历，每次查询1分钟的数据，共查询60次，以避免分页查询。当前版本为V6，老版本参考数据查询接口V5。
鉴权说明
易盾智能风控服务使用签名认证方法对接口进行鉴权，所有接口每一次请求都需要包含签名信息（signature 参数），以验证用户身份，防止信息被恶意篡改。目前支持MD5签名算法，详细信息请参见接口鉴权。
接入须知
- 数据时间有效性
- 支持查询最近一个月的所有数据
- SDK上报数据后即可查询，支持多次重复查询
- 导出数据量
- 采用深度分页方式返回数据：如果查询条件返回数据量超过1万条，会以分页形式返回；下一页查询标识，见
startFlag请求参数说明 - 如想及时获取数据，建议采用定时任务每分钟调用一次，每次查询前一分钟内的全部数据，按分钟粒度查询很少会超过1万条，避免分页查询
- 采用深度分页方式返回数据：如果查询条件返回数据量超过1万条，会以分页形式返回；下一页查询标识，见
- 查询频率限制
- 该接口返回数据量较大，不支持高并发查询，查询频率过快可能会被拒绝，拒绝后稍后重试即可
- 建议两次查询间隔为10s以上
- 示例demo地址
- https://github.com/yidun/irisk-openapi-demo
请求说明
请求地址
| 名称 | 值 |
|---|---|
| HTTP URL | http://ir-open.dun.163.com/v6/risk/detail |
| HTTP Method | POST |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Content-Type | String | 是 | 固定值："Content-Type:application/json" |
请求参数
请求参数分为：公共参数，接口参数。其中，公共参数请见公共请求参数；接口参数如下：
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| beginTimestamp | Long | 是 | 开始时间戳，单位： ms, 不能小于30天前 |
| endTimestamp | Long | 是 | 结束时间戳，单位： ms, 结束时间戳与开始时间戳的时间间隔不能大于30天 |
| startFlag | String | 否 | 用于分页查询的关联标记。第一次查询时，该字段填充空字符串""或不传该字段均可，后续查询时，需要判断上一次查询的返回数据中startFlag值，如果startFlag不为空字符串""，表示需要分页查询。当使用分页查询时，startFlag字段使用上一次返回值填充，其他字段保持不变，继续调用查询接口。如果startFlag为空字符串""，例如返回数据为{"code": 200, "msg": "ok", "data": {"size": 100, "startFlag": "", "detail": [{},...]}}，表示不需要分页查询，可以使用新的时间条件查询。 |
| account | String | 否 | 用户/玩家的账号 |
| accounts | String | 否 | 用户/玩家的账号集合json字符串，如请求参数示例 |
| roleId | String | 否 | 用户/玩家的角色ID |
| roleIds | String | 否 | 用户/玩家的角色ID集合json字符串，如请求参数示例 |
| riskLevel | Integer | 否 | 风险等级，0-正常，1-低风险，2-中风险，3-高风险，4-可信源 |
| ip | String | 否 | 服务端ip地址 |
| ips | String | 否 | 服务端ip地址集合json字符串，如请求参数示例 |
| sdkIp | String | 否 | 客户端ip地址 |
| sdkIps | String | 否 | 客户端ip地址集合json字符串，如请求参数示例 |
| packageName | String | 否 | 包名 |
| appVersion | String | 否 | app版本 |
| checkSource | Integer | 否 | 检测来源，0-SDK检测请求，1-服务端检测请求(仅限Android/iOS/Windows平台) |
请求参数示例
{
"businessId": "xxx966f73yyy59440583zzz9bfcc79df",
"secretId": "nnn966f73yyy59440583zzz9bfcc79dc",
"timestamp": ${currentTimeMs},
"nonce": "mmm888f73yyy59440583zzz9bfcc79de",
"version": "600",
"signature": "lll888f73yyy59440583zzz9bfcc79da",
"beginTimestamp": 1667959831798,
"endTimestamp": 1667959915103,
"startFlag": "",
"account": "zzzzzzz",
"accounts":"[\"account01\",\"account02\"]",
"roleId": "yyyyyyy",
"roleIds":"[\"roleId01\",\"roleId02\"]",
"riskLevel": 1,
"packageName": "com.aaa.bbb",
"appVersion": "1.0.2",
"ip": "192.168.1.1",
"ips":"[\"ip01\",\"ip02\"]",
"sdkIp": "192.168.0.1",
"sdkIps":"[\"sdkIp01\",\"sdkIp02\"]",
"checkSource": 1
}
响应
响应结果
响应数据格式为：JSON。
响应头为：Content-Type:application/json，具体如下：
| 参数 | 类型 | 描述 |
|---|---|---|
| code | Integer | 响应码，正常情况下为200，异常时，见 附录响应码定义 |
| msg | String | 响应码说明，正常情况下返回“ok”，异常时，见 附录响应码定义 |
| data | JSONObject | 返回数据格式， 如下 |
| 参数 | 类型 | 说明 |
|---|---|---|
| size | Integer | 本次查询返回的数据条数 |
| startFlag | String | 用于分批查询的关联标记。1. 当查询需要分批返回数据时，表示下一批数据起始标记。2. 当该值返回为空字符串""时，表示数据都已经返回，不需要继续执行下一批查询 |
| detail | Array<DetailData> | 具体返回数据，每条数据类型见明细数据DetailData结构 |
| 参数 | 类型 | 说明 |
|---|---|---|
| receiveTime | String | 时间 |
| platform | String | 平台 |
| businessId | String | 业务ID |
| businessName | String | 业务名称 |
| token | String | Token |
| taskId | String | TaskId |
| checkSource | String | 检测来源 |
| sceneType | String | 场景类型 |
| sessionId | String | SessionId |
| timeoutToken | String | 超时Token |
| activityId | String | 活动的唯一标识 |
| account | String | 账号 |
| roleId | String | 角色ID |
| nickname | String | 昵称 |
| phone | String | 手机号码 |
| identity | String | 用户身份 |
| payUser | String | 付费用户 |
| verified | String | 实名认证 |
| gender | String | 性别 |
| level | String | 等级 |
| registerChannel | String | 注册渠道 |
| registerDays | String | 注册天数 |
| onlineTimes | String | 在线时长，单位：s |
| appName | String | 应用名称 |
| packageName | String | 包名 |
| author | String | 作者 |
| signV1 | String | 签名V1 |
| signV2 | String | 签名V2 |
| appVersion | String | app版本 |
| gameVersion | String | 游戏版本 |
| assetVersion | String | 资源版本 |
| sdkVersion | String | SDK版本 |
| server | String | 服务器名称 |
| serverId | String | 服务器ID |
| gameJson | String | GameJson |
| deviceId | String | 设备ID |
| deviceType | String | 设备类型 |
| deviceBrand | String | 设备品牌 |
| deviceModel | String | 设备型号 |
| osVersion | String | 系统版本 |
| carrierName | String | 运营商 |
| emulatorDid | String | 主机ID |
| localCacheId | String | 本地缓存ID |
| mac | String | MAC地址(仅Windows平台) |
| deviceGuid | String | 设备Guid(仅Windows平台) |
| networkType | String | 联网类型 |
| location | String | 地区 |
| sdkIp | String | SDK IP |
| ip | String | 服务端IP |
| isp | String | IP运营商 |
| sceneData | String | 场景信息 |
| riskLevel | String | 风险等级 |
| matchedRiskTags | String | 命中的风险标签, 以";"连接 |
| matchedTypes | String | 命中的风险标签Type, 以";"连接 |
| matchedRules | String | 命中的规则编号, 以";"连接 |
| execAction | String | 执行动作 |
| protectionResult | String | 防护结果 |
| evidence | String | 风险证据信息，用于说明当前行为被判定为风险行为的原因, 多个以";"连接 |
| phoneCarrierName | String | 号码运营商 |
| phoneLocation | String | 号码归属地 |
| phoneRiskType | String | 号码风险类型 |
| phoneRiskLevel | String | 号码风险等级 |
| phoneRiskScore | String | 号码风险分值 |
| ipRiskType | String | IP风险类型 |
| ipRiskLevel | String | IP风险等级 |
| ipRiskScore | String | IP风险分值 |
| extData | String | 拓展信息 |
响应结果示例
- 当不需要执行下一批次查询时：
{
"code": 200,
"msg": "ok!",
"data": {
"size": 1,
"startFlag": "",
"detail": [
{
"receiveTime": "2024-01-29 10:07:10",
"platform": "ANDROID",
"businessId": "xxxxxxxx",
"businessName": "xxxxxx",
"token": "xxxxxx",
"taskId": "xxxxxxx",
"checkSource": "客户服务端检测请求",
"sceneType": "",
"sessionId": "",
"timeoutToken": "false",
"activityId": "QAactivityId",
"account": "QA6account",
"roleId": "QA6roleId01",
"nickname": "",
"phone": "18633261111",
"identity": "",
"payUser": "",
"verified": "",
"level": "",
"registerChannel": "weixin",
"registerDays": "27",
"gender": "male",
"appName": "",
"packageName": "",
"author": "",
"signV1": "",
"signV2": "",
"appVersion": "",
"gameVersion": "",
"assetVersion": "",
"sdkVersion": "",
"server": "",
"serverId": "",
"deviceId": "",
"deviceType": "真机",
"deviceBrand": "",
"deviceModel": "",
"osVersion": "",
"carrierName": "",
"emulatorDid": "",
"localCacheId": "",
"networkType": "",
"location": "",
"sdkIp": "",
"ip": "183.131.182.111",
"isp": "xxx",
"sceneData": "{\"registerType\": \"userPassword\",\"registerChannel\": \"weixin\",\"gender\": \"male\", \"inviter\": \"inviterNameQA\",\"hashPassword\": \"HPASW00001\",\"clickId\": \"click_id000001\"}",
"riskLevel": "低风险",
"matchedRiskTags": "其它风险-数据异常-token过期",
"matchedTypes": "124001",
"matchedRules": "R1111111(系统策略)",
"execAction": "放行",
"protectionResult": "--",
"evidence": "",
"phoneCarrierName": "联通",
"phoneLocation": "河北-保定",
"phoneRiskType": "",
"phoneRiskLevel": "高风险",
"phoneRiskScore": "1.0",
"ipRiskType": "",
"ipRiskLevel": "",
"ipRiskScore": "",
"extData": "{\"Testjson\":\"TEST\"}"
}
]
},
"ok":true
}
- 当需要继续执行下一批次查询时：
{
"code": 200,
"msg": "ok!",
"data": {
"size": 10000,
"startFlag": "MTY2NDQzMzU4NTYxMSMxZTlxdjR1ZGpjaDk5djM0MDBmbmVidmdkZDAwOXdxdQ==",
"detail": [
{
"receiveTime": "2024-01-29 10:07:10",
"platform": "ANDROID",
"businessId": "xxxxxxxx",
"businessName": "xxxxxx",
"token": "xxxxxx",
"taskId": "xxxxxxx",
"checkSource": "客户服务端检测请求",
"sceneType": "",
"sessionId": "",
"timeoutToken": "false",
"activityId": "QAactivityId",
"account": "QA6account",
"roleId": "QA6roleId01",
"nickname": "",
"phone": "18633261111",
"identity": "",
"payUser": "",
"verified": "",
"level": "",
"registerChannel": "weixin",
"registerDays": "27",
"gender": "male",
"appName": "",
"packageName": "",
"author": "",
"signV1": "",
"signV2": "",
"appVersion": "",
"gameVersion": "",
"assetVersion": "",
"sdkVersion": "",
"server": "",
"serverId": "",
"deviceId": "",
"deviceType": "真机",
"deviceBrand": "",
"deviceModel": "",
"osVersion": "",
"carrierName": "",
"emulatorDid": "",
"localCacheId": "",
"networkType": "",
"location": "",
"sdkIp": "",
"ip": "183.131.182.111",
"isp": "xxx",
"sceneData": "{\"registerType\": \"userPassword\",\"registerChannel\": \"weixin\",\"gender\": \"male\", \"inviter\": \"inviterNameQA\",\"hashPassword\": \"HPASW00001\",\"clickId\": \"click_id000001\"}",
"riskLevel": "低风险",
"matchedRiskTags": "其它风险-数据异常-token过期",
"matchedTypes": "124001",
"matchedRules": "R1111111(系统策略)",
"execAction": "放行",
"protectionResult": "--",
"evidence": "",
"phoneCarrierName": "联通",
"phoneLocation": "河北-保定",
"phoneRiskType": "",
"phoneRiskLevel": "高风险",
"phoneRiskScore": "1.0",
"ipRiskType": "",
"ipRiskLevel": "",
"ipRiskScore": "",
"extData": "{\"Testjson\":\"TEST\"}"
},
//... 此处省略9999条数据
]
},
"ok":true
}
响应返回码
响应返回码见：响应返回码
接入示例代码
服务端 SDK 接入
推荐使用我们提供的服务端 SDK 进行接入（目前支持 Java 和 Go 两种语言），不但可以节省接入成本，实现更快速的集成，并享有灵活的请求配置选项，同时 SDK 内置了错误重试、熔断降级等功能，提升服务可用性。点击 服务端 SDK 接入指引了解更多。
