数据查询接口

2024.02.29 15:07:11

    接口说明

    本接口的功能是智能风控明细数据查询,主要用于检测结果数据同步。接口支持根据指定时间窗口查询该时间段内的全部检测数据,支持分页查询,每页最多返回1万条。建议时间区间不要太大,尽量使用较小时间段遍历查询。例如如果想查最近一个小时的数据,可按1分钟的时间段进行遍历,每次查询1分钟的数据,共查询60次,以避免分页查询。当前版本为V5,老版本参考数据查询接口V4

    鉴权说明

    易盾智能风控服务使用签名认证方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature 参数),以验证用户身份,防止信息被恶意篡改。目前支持MD5签名算法,详细信息请参见接口鉴权

    接入须知

    • 数据时间有效性
      • 支持查询最近一个月的所有数据
      • SDK上报数据后即可查询,支持多次重复查询
    • 导出数据量
      • 采用深度分页方式返回数据:如果查询条件返回数据量超过1万条,会以分页形式返回;下一页查询标识,见startFlag请求参数说明
      • 如想及时获取数据,建议采用定时任务每分钟调用一次,每次查询前一分钟内的全部数据,按分钟粒度查询很少会超过1万条,避免分页查询
    • 查询频率限制
      • 该接口返回数据量较大,不支持高并发查询,查询频率过快可能会被拒绝,拒绝后稍后重试即可
      • 建议两次查询间隔为10s以上
    • 示例demo地址
      • https://github.com/yidun/irisk-openapi-demo

     

    请求说明

    请求地址

    名称
    HTTP URL http://ir-open.dun.163.com/v5/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 用户/玩家的账号
    roleId String 用户/玩家的角色ID
    riskLevel Integer 风险等级,0-正常,1-低风险,2-中风险,3-高风险,4-可信源
    ip String 服务端ip地址
    sdkIp String 客户端ip地址
    packageName String 包名(仅限Android/iOS平台)
    appVersion String app版本(仅限Android/iOS平台)

     

    请求参数示例

    {
        "businessId": "xxx966f73yyy59440583zzz9bfcc79df",
        "secretId": "nnn966f73yyy59440583zzz9bfcc79dc",
        "timestamp": ${currentTimeMs},
        "nonce": "mmm888f73yyy59440583zzz9bfcc79de",
        "version": "500",
        "signature": "lll888f73yyy59440583zzz9bfcc79da",
        "beginTimestamp": 1667959831798,
        "endTimestamp":  1667959915103,
        "startFlag": "",
        "account":  "zzzzzzz",
        "roleId":  "yyyyyyy",
        "riskLevel":  1,
        "packageName":  "com.aaa.bbb",
        "appVersion":  "1.0.2",
        "ip":  "192.168.1.1",
        "sdkIp": "192.168.0.1"
    }
    
    

    响应

    响应结果

    响应数据格式为:JSON。

    响应头为:Content-Type:application/json,具体如下:

    参数 类型 描述
    code Integer 响应码,正常情况下为200,异常时,见 附录响应码定义
    msg String 响应码说明,正常情况下返回“ok”,异常时,见 附录响应码定义
    data JSONObject 返回数据格式, 如下

    数据格式:

    参数 类型 说明
    size Integer 本次查询返回的数据条数
    startFlag String 用于分批查询的关联标记。1. 当查询需要分批返回数据时,表示下一批数据起始标记。2. 当该值返回为空字符串""时,表示数据都已经返回,不需要继续执行下一批查询
    detail Array<DetailData> 具体返回数据,每条数据类型见明细数据DetailData结构

    明细数据DetailData结构

    不同平台明细数据有所差异,具体参照“数据查询”页面中“自定义列”中字段

    • Android/iOS平台:
    参数 类型 说明
    businessId String 业务ID
    businessName String 业务名称
    token String token
    taskId String TaskID
    receiveTime String 时间
    sessionId String 会话ID
    trackId String TrackID
    account String 角色账号
    roleId String 角色ID
    nickname String 昵称
    server String 服务器
    serverId String 服务器ID
    level String 角色等级
    currentOnlineTime String 登录时长
    target String 活动操作的目标
    activityId String 活动的唯一标识
    phone String 手机号码
    appName String 应用名称
    packageName String 包名
    appVersion String app版本
    gameVersion String 游戏版本
    assetVersion String 资源版本
    signHash String 签名HASH
    signMd5 String 签名MD5
    sdkVersion String SDK版本
    localFeatureVersion String 本地特征版本
    deviceType String 设备类型
    model String 品牌型号
    deviceOs String 设备系统
    osVersion String 系统版本
    deviceId String 设备ID
    emulatorDid String 主机ID
    networkType String 网络类型
    ip String 服务端IP地址
    sdkIp String 客户端SDK IP地址
    location String 地区
    riskLevel String 风险等级
    execAction String 执行动作
    protectionResult String 防护结果
    matchedRiskTags String 命中的风险标签, 以";"连接
    evidence String 风险证据信息,用于说明当前行为被判定为风险行为的原因, 多个以";"连接
    • Windows平台
    参数 类型 说明
    businessId String 业务ID
    businessName String 业务名称
    token String token
    taskId String TaskID
    receiveTime String 时间
    account String 角色账号
    roleId String 角色ID
    nickname String 昵称
    server String 服务器
    serverId String 服务器ID
    level String 角色等级
    userGuid String 用户Guid
    currentOnlineTime String 登录时长
    target String 活动操作的目标
    activityId String 活动的唯一标识
    appName String 应用名称
    sdkVersion String SDK版本
    packVersion String 加固版本
    localFeatureVersion String 本地特征版本
    platform String 平台
    hardDiskId String 磁盘序列号
    mac String mac地址
    deviceGuid String 设备Guid
    osVersion String 系统版本
    screenResolution String 屏幕分辨率
    osDesc String 操作系统
    processorDesc String CPU
    memoryDesc String 内存
    ip String 服务端IP地址
    sdkIp String 客户端SDK IP地址
    location String 地区
    riskLevel String 风险等级
    execAction String 执行动作
    protectionResult String 防护结果
    matchedRiskTags String 命中的风险标签, 以";"连接
    • Web平台
    参数 类型 说明
    businessId String 业务ID
    businessName String 业务名称
    token String token
    taskId String TaskID
    receiveTime String 时间
    trackId String TrackID
    account String 角色账号
    roleId String 角色ID
    nickname String 昵称
    server String 服务器
    level String 角色等级
    target String 活动操作的目标
    activityId String 活动的唯一标识
    appName String 应用名称
    sdkVersion String SDK版本
    platform String 平台
    webType String WEB类型
    browserName String 浏览器名称
    browserVersion String 浏览器版本
    kernelName String 内核名称
    language String 语言
    platformInfo String 所处平台
    deviceId String 设备ID
    mac String mac地址
    ip String 服务端IP地址
    sdkIp String 客户端SDK IP地址
    location String 地区
    riskLevel String 风险等级
    execAction String 执行动作
    matchedRiskTags String 命中的风险标签, 以";"连接
    • 小程序平台
    参数 类型 说明
    businessId String 业务ID
    businessName String 业务名称
    token String token
    taskId String TaskID
    receiveTime String 时间
    trackId String TrackID
    account String 角色账号
    roleId String 角色ID
    nickname String 昵称
    server String 服务器
    level String 角色等级
    target String target
    activityId String activityId
    phone String 电话号码
    sdkVersion String SDK版本
    miniProgramVersion String 小程序版本
    model String 品牌型号
    deviceId String 设备ID
    clientPlatform String 客户端平台
    miniProgramPlatform String 小程序平台
    networkType String 网络类型
    ip String 服务端IP地址
    sdkIp String 客户端SDK IP地址
    location String 地区
    riskLevel String 风险等级
    execAction String 执行动作
    matchedRiskTags String 命中的风险标签, 以";"连接
    • API模式
    参数 类型 说明
    businessId String 业务ID
    businessName String 业务名称
    taskId String TaskID
    receiveTime String 时间
    account String 角色账号
    roleId String 角色ID
    nickname String 昵称
    server String 服务器
    level String 角色等级
    target String target
    activityId String activityId
    ip String 服务端IP地址
    location String 地区
    riskLevel String 风险等级
    execAction String 执行动作
    matchedRiskTags String 命中的风险标签, 以";"连接

    响应结果示例

    • 当不需要执行下一批次查询时:
    {
        "code": 200,
        "msg": "ok!",
        "data": {
            "size": 100,
            "startFlag": "",
            "detail": [
                {
                    "businessId": "xxx",
                    "businessName": "xxxx",
                    "roleServer": "xxxx",
                    "appVersion": "2.1.1",
                    "riskLevel": "高风险",
                    "deviceOs": "IOS",
                    "deviceId": "CAhLczArTdNFSlQBUQaQSjg3eyndeBft",
                    "osVersion": "11.0",
                    "model": "iPhone 12",
                    "level": "",
                    "packageName": "com.aaa.bbb",
                    "networkType": "2G",
                    "deviceType": "模拟器",
                    "signHash": "2022a0b1ccddeeffa0b1ccdd99bb9977",
                    "roleId": "RoT-1025788773",
                    "appName": "appName001",
                    "execAction": "放行",
                    "ip": "115.236.119.140",
                    "sdkIp": "127.0.0.1",
                    "sessionId": "sessionId001",
                    "token": "rMc6A1zRxhFEDFRQAQKVXsA+utHq5o3l",
                    "emulatorDid": "",
                    "receiveTime": "2022-09-29 14:39:45",
                    "matchedRiskTags": "环境风险-模拟器-通用模拟器;环境风险-云真机-云真机设备;外挂风险-加速挂-烧饼加速器",
                    "localFeatureVersion": "99",
                    "assetVersion": "0.1.1",
                    "nickname": "nickname9",
                    "gameVersion": "1.0.1",
                    "signMd5": "adffdgsdfgsfdhgdsfgh",
                    "sdkVersion": "1.1.3",
                    "location": "中国-浙江-杭州",
                    "account": "roleaccount887142103",
                    "currentOnlineTime": "10h 13min 9s",
                    "taskId": "xxxx",
                    "activityId": "xxxx",
                    "target": "target01",
                    "phone": "1xxxxxxxxxx"
    
                }
            ]
      },
      "ok":true
    }
    
    • 当需要继续执行下一批次查询时:
    {
        "code": 200,
        "msg": "ok!",
        "data": {
            "size": 10000,
            "startFlag": "MTY2NDQzMzU4NTYxMSMxZTlxdjR1ZGpjaDk5djM0MDBmbmVidmdkZDAwOXdxdQ==",
            "detail": [
                {
                    "businessId": "xxx",
                    "businessName": "xxxx",
                    "roleServer": "xxxx",
                    "appVersion": "2.1.1",
                    "riskLevel": "高风险",
                    "deviceOs": "IOS",
                    "deviceId": "CAhLczArTdNFSlQBUQaQSjg3eyndeBft",
                    "osVersion": "11.0",
                    "model": "iPhone 12",
                    "level": "",
                    "packageName": "com.aaa.bbb",
                    "networkType": "2G",
                    "deviceType": "模拟器",
                    "signHash": "2022a0b1ccddeeffa0b1ccdd99bb9977",
                    "roleId": "RoT-1025788773",
                    "appName": "appName001",
                    "execAction": "放行",
                    "ip": "115.236.119.140",
                    "sdkIp": "127.0.0.1",
                    "sessionId": "sessionId001",
                    "token": "rMc6A1zRxhFEDFRQAQKVXsA+utHq5o3l",
                    "emulatorDid": "",
                    "receiveTime": "2022-09-29 14:39:45",
                    "matchedRiskTags": "环境风险-模拟器-通用模拟器;环境风险-云真机-云真机设备;外挂风险-加速挂-烧饼加速器",
                    "localFeatureVersion": "99",
                    "assetVersion": "0.1.1",
                    "nickname": "nickname9",
                    "gameVersion": "1.0.1",
                    "signMd5": "adffdgsdfgsfdhgdsfgh",
                    "sdkVersion": "1.1.3",
                    "location": "中国-浙江-杭州",
                    "account": "roleaccount887142103",
                    "currentOnlineTime": "10h 13min 9s",
                    "taskId": "xxxx",
                    "activityId": "xxxx",
                    "target": "target01",
                    "phone": "1xxxxxxxxxx"
    
                },
                //... 此处省略9999条数据
            ]
      },
      "ok":true
    }
    

    响应返回码

    响应返回码见:响应返回码

    接入示例代码

    开发工具集(SDK)接入

    为方便开发者调试和接入API,我们提供了配套的开发工具集(SDK),用于简化API接入流程。SDK中各接口调用方式基本相同,接入方式统一,并提供了一些接口调用过程中常见的异常处理方案。以下介绍了SDK的使用流程,以及使用SDK的简单示例。

    • 准备工作

    准备步骤详见通用步骤

    • 使用方法

    该接口的使用方法可参考以下SDK demo:

    JAVA SDK demo

    GOLANG SDK demo

    Online Chat Tel:95163223 Free trial