网易易盾手游智能反外挂API(服务端)接入文档

2021.07.19 11:52:25

    一、接入说明

    易盾手游智能反外挂服务,对外提供Open API接口服务,包括反外挂数据和举报数据等接口类别,如下:

    二、接入步骤

    2.1 获取安全凭证

    在调用Open API服务接口之前,需要从【易盾官网-服务管理-已开通业务】获取AppId和AppKey,用于计算接口请求认证签名,见认证参数token生成说明

    2.2 测试联调

    • 从客户端发送数据,验证对应Open API接口响应数据

    三、接口清单

    3.1 接口通用说明

    • 传输协议:支持Http和Https协议
    • 请求方法:默认为POST
    • 字符编码:请求参数与响应数据,统一为UTF-8编码
    • 请求API结构说明
      • 请求API符合Http请求规范,由三部分组成:请求Header,请求URL,请求Body。
      • 请求的Body数据,分为公共参数,和API私有参数。
    名称 组成 描述 备注
    请求URL-域名 域名 例如http://open-yb.dun.163.com 线上域名
    请求URL-路径 路径Path 例如/api/open/v1/risk/detail_data/list API路径
    请求Header Content-Type:application/json 参数格式 请求参数为JSON格式
    请求Body 公共请求参数 参数说明见下文 公共请求参数,用于标识产品,及接口调用认证。在每个接口单独的接口文档中不再对这些参数进行说明,每次请求均需要携带这些参数
    请求Body 接口私有参数 详见每个接口定义描述 每个接口特有参数,
    • 公共请求参数
    名称 类型 是否必填 描述
    appId String 每个应用接入时,会分配AppID,和对应密钥AppKey。从【易盾官网-服务管理-已开通业务】页面获取。
    timestamp Long 调用接口当前时间,单位毫秒,防止重放
    nonce String 随机码,防止重放
    token String 使用appKey签名的数据,校验权限,生成方式,见附录 认证参数token生成说明
    • 请求Body参数示例
    {"appId":"xxx8888949","timestamp":"${currentTime},"token":"${sign}","nonce":"111","beginDateTime":1564041324000,"endDateTime":1574127724519,"roleId": "00992755211_11", "deviceId": "", "userAccount": "", "roleName": ""}
    
    • 响应数据结构说明 大部分接口响应数据,是JSON格式,描述如下:
    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义
    data JSONObject或Array 返回数据

    3.2 反外挂嫌疑明细数据查询

    3.2.1 接口用途

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

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

    3.2.2 接入须知

    • 数据时间有效性
      • 可以导出最近一个月的所有数据
      • 可以导出Open API接入之前的数据
    • 导出数据量
      • 采用深度分页方式返回数据:如果查询条件返回数据量超过1万条,会以分页形式返回;下一页查询标识,见startFlag请求参数说明
      • 建议每次查询1分钟前的数据,时间跨度也是1分钟,按1分钟时间窗口,周期性滑动拉取数据。这个时间粒度,很少会超过1万条。
      • 支持去重导出。在查询时间范围内,如果以下字段内容都相同时,仅会返回一条记录。字段如下:appId,deviceId,roleId,roleName,roleAccount,plugRisk,plugType,envRisk,envType,otherRisk,otherType字段解释,见接口响应说明
    • 数据返回格式
      • 有两种:Json格式,LinedText分行文本格式
      • 对于查询返回数据量,经常大于1千条的,建议使用LinedText格式,反序列化性能优于Json格式。
    注意事项

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


    3.2.3 使用形式

    • 接口地址: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)返回的嫌疑明细数据是相同的,新版接口仅仅对旧版接口返回的数据进行了外层封装,封装形式见响应数据结构说明。目前旧版接口已废弃,但仍继续维护,已经接入旧版接口的用户可继续正常使用,推荐使用新版接口。


    3.2.4 请求参数

    • 请求参数:包括公共参数,和接口参数
    名称 类型 是否必填 描述
    duplicate Integer 1:不去重查询;0:去重查询(默认)
    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
    去重说明

    去重查询是指,在查询时间范围内,如果以下字段内容都相同时,仅会返回一条记录。字段如下:appId,deviceId,roleId,roleName,roleAccount,plugRisk,plugType,envRisk,envType,otherRisk,otherType字段解释,见接口响应说明

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

    {"appId":"${APPID}","timestamp":${currentTime},"token":"${sign}","nonce":"111","duplicate":1,"beginDateTime":1564041324000,"endDateTime":1574127724519,"startFlag":""}
    


    3.2.6 响应结果

    • 响应结果,支持两种格式: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版本
    antiSdkVersion String 反外挂sdk版本
    cheatInfo1 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行列名
    第...行 ... ...


    3.2.7 响应结果示例

    • 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"
                },
                {
                    "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"
                }
                  ]
        }
    }
    
    • LinedText格式示例如下:

    image title

    • 异常返回的数据
      • 响应头为:Content-Type:application/json

    数据JSON格式如下:

    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义
    • 异常数据示例
    {  
        "msg": "未授权或者授权已过期",  
        "code": 401 
    } 
    

    3.3 反外挂角色ID存在验证


    3.3.1 接口用途

    本接口用于验证角色ID,是否存在嫌疑上报数据中。支持批量验证。


    3.3.2 接入须知

    注意事项

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


    3.3.3 使用形式

    • 接口地址:http://open-yb.dun.163.com/api/open/v1/risk/doubtful/checkroleidexist
    • 请求方法:POST
    • 请求头:Content-Type:application/json


    3.3.4 请求参数

    • 请求参数:包括公共参数,和接口参数
    名称 类型 是否必填 描述
    beginTime Long 开始时间,单位毫秒
    endTime Long 结束时间,单位毫秒
    roleIds Array<String> 数组最大个数:100


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

    {
       "appId": "xxx8888894",
        "timestamp": ${currentTime},
        "nonce":111,
        "token": "${sign}",
        "roleIds":  ["roleTestid","roleTestid2","TransTest"],
        "beginTime":1575388800000,
        "endTime": 1585545601000
    }
    
    


    3.3.6 响应结果

    • 响应数据格式:JSON
      • 响应头为:Content-Type:application/json
    参数名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义
    data RoleInfo 返回数据,格式见【RoleInfo数据格式】
    lastestEventTime Long 不为默认值0时,表示可供查询数据的最新时间
    • RoleInfo数据格式:
    名称 类型 描述
    total Integer 返回记录条数,去重
    roleIds Array<String> 记录明细


    3.3.7响应结果示例:

    • 存在角色ID时:
    {
      "code": 0,
       "msg": null,
       "data": {
          "total": 2,
          "roleIds": [
              "TransTest",
              "roleTestid"
          ]
      },
      "lastestEventTime": 0
    }
    
    • 不存在角色ID时:
    {
    
      "code": 0,
      "msg":"当前查询条件无数据返回,可能因为数据不存在或者数据处理未完成,可供查询数据的最新时间见lastestEventTime字段。",
      "data": {
          "total": 0,
          "roleIds": []
      },
     "lastestEventTime": 1578366604897
    }
    

    注意:

    注意

    1. 当返回无数据时,数据处理可能存在延时或者数据不存在。
    2. 当设置查询的结束时间endTime小于lastestEventTime时,如果返回无数据,则确认是数据不存在。
    3. 自动封禁有风险,操作请谨慎,建议综合参考其它因素。

    3.4 举报数据上报


    3.4.1 接口用途

    上报举报数据。再由易盾给出被举报方的相关验证信息。


    3.4.2 使用形式

    • 接口地址:http://open-yb.dun.163.com/api/open/v1/risk/report
    • 请求方法:POST
    • 请求头:Content-Type:application/json


    3.4.3 请求参数

    接口参数如下:

    参数名称 类型 字符长度 是否必填 描述
    appId String 10 AppID
    reportType Integer 举报类型. 0:外挂, 1:工作室, 2:言语辱骂, 3:违规宣传, 4:消极游戏|演员|挂机, 5:游戏漏洞|bug
    reportTime Long 举报时间
    reportRoleAccount String 最大255 举报用户账号
    reportRoleId String 最大255 举报用户角色Id
    reportRoleName String 最大255 举报用户角色名
    reportDeviceId String 最大255 举报用户设备标识
    reportDesc String 最大255 举报描述
    verificationSpan Integer 查询跨度,以小时为单位,建议最大为24小时
    reportedRoleAccount String 最大255 被举报用户账号
    reportedRoleId String 最大255 被举报用户角色
    reportedRoleName String 最大255 被举报用户名称
    reportedRoleServer String 最大255 被举报用户服务器
    reportedDeviceId String 最大255 被举报用户设备标识
    reportedPlatform Integer 被举报方系统 1:ios ; 2:android


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

    {"appId":"xxx8888861","timestamp":${currentTime},"token":"${sign}",
    "nonce":"111","reportType":1,"beginDateTime":1564041324000,
    "endDateTime":1574127724519,"reportType":1,"reportTime":1564041324000,"reportRoleAccount":"xxx","reportRoleName":"xxx",
    "reportDeviceId":"xxx","reportDesc":"xxx","verificationSpan":2,"reportedRoleAccount":"xxx","reportedRoleId":"xxx",
    "reportedRoleName":"xxx","reportedRoleServer":"xxx","reportedDeviceId":"xxx","reportedPlatform":2}
    
    


    3.4.5 响应结果

    • 响应数据格式: JSON
      • 响应头为:Content-Type:application/json
    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义


    3.4.6 响应数据示例:

    { "msg": "ok!", "code": 200 }
    

    3.5 举报数据验证查询


    3.5.1 接口用途

    查询举报数据的相关验证信息。


    3.5.2 使用形式

    • 接口地址:http://open-yb.dun.163.com/api/open/v1/risk/report/list
    • 请求方法:POST
    • 请求头:Content-Type:application/json


    ** 3.5.3 请求参数**

    接口参数如下:

    参数名称 类型 字符长度 是否必填 描述
    startTime Long 举报时间查询起始时间
    endTime Long 举报时间查询终止时间
    reportRoleAccount String 最大255 举报用户账号
    reportRoleId String 最大255 举报用户角色Id
    reportRoleName String 最大255 举报用户角色名
    reportDeviceId String 最大255 举报用户设备标识
    reportedRoleAccount String 最大255 被举报用户账号
    reportedRoleIds Array<String> 最大255 被举报用户角色
    reportedRoleName String 最大255 被举报用户名称
    reportedRoleServer String 最大255 被举报用户服务器
    reportedDeviceId String 最大255 被举报用户设备标识
    defineResult Integer 风险处理结果(1:拦截成功;0:未拦截)


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

    {"appId":"xxx8888861","timestamp":${currentTime},"token":"${sign}",
    "nonce":"111","reportType":1,"startTime":1564041324000,
    "endTime":1574127724519,"defendResult":1,"reportRoleAccount":"xxx","reportRoleName":"xxx","reportDeviceId":"xxx","reportedRoleAccount":"xxx","reportedRoleIds":["xxx"],
    "reportedRoleName":"xxx","reportedRoleServer":"xxx","reportedDeviceId":"xxx"}
    
    


    3.5.5 响应结果

    • 响应数据格式,分为两种:
      • 正常返回的数据,使用LinedText格式(因为数据量大,如果使用JSON,反序列化比较慢)。其中,响应头为:Content-type: text/plain;charset=utf-8
      • 异常返回的数据,使用JSON格式,其中,响应头为:Content-Type:application/json
    • LinedText格式(即行文本格式)
      • 响应头为:Content-type: text/plain;charset=utf-8
      • 数据以\n分行,每行的各个字段以\t键分隔。
      • 从第一行,到第四行,用于描述数据信息。
      • 从第5行开始,为嫌疑数据记录。
      • 格式样例
    行号 每行数据格式 描述
    第1行 startFlag=${下一批数据起始标记} 1. 当查询需要分批返回数据时,表示下一批数据起始标记。2. 当为null值,表示数据都已经返回,不需要继续执行下一批查询。注意:当前该字段都返回null值,为扩展保留字段
    第2行 separator=${列分隔符号} 行中的不同列之间分隔符,如Tab,或\001等
    第3行 colums=${数据列名称} 数据列名称,以"列分隔符"切分
    第4行 size=${总行数} 数据总行数,可以为空值
    第5行 每行数据记录 数据记录,从第5行开始
    第...行 ... ...


    3.5.6 响应结果示例

    • 正常数据示例,LinedText格式,如下: image title
    • 异常返回的数据
      • 响应头为:Content-Type:application/json

    数据JSON格式如下:

    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义
    • 异常数据示例
    {  
        "msg": "未授权或者授权已过期",  
        "code": 401 
    } 
    

    3.6 模拟点击详情数据查询


    3.6.1 接口用途

    查询模拟点击详情数据信息。


    3.6.2 接入须知

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


    3.6.3 使用形式

    • 接口地址:http://open-yb.dun.163.com/api/open/v1/risk/simulatedClick/detail
    • 请求方法:POST
    • 请求头:Content-Type:application/json


    3.6.4 请求参数

    • 请求参数:包括公共参数,和接口参数
    参数名称 类型 字符长度 是否必填 描述
    statusCode Integer 查询数据的类型. 1 : 嫌疑数据, 2 : 确认数据
    startTime Long 查询数据的开始时间戳, 开始时间戳不能小于当前时间戳减31天前的时间戳(起止时间范围不能超过7天)
    endTime Long 查询数据的结束时间戳, 结束时间戳不能大于当前时间戳(起止时间范围不能超过7天)
    roleName String 最大255 查询用户的角色名称
    startFlag String 用于分页查询的关联标记。第一次查询时,该字段填充""空字符串,后续查询时,需要判断上一次查询的返回数据中startFlag值,如果返回的startFlag不为""空字符串,表示需要分页查询。当使用分页查询时,请求参数startFlag字段使用上一次返回值填充,其他字段保持不变,继续调用查询接口。如果返回的startFlag为""空字符串,表示不需要分页查询,可以使用新的时间条件查询。


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

    {
        "appId": "xxx8888861",
        "timestamp":${currentTime},
        "token":"${sign}",
        "nonce":"111",
        "statusCode":1,
        "startTime":1564041324000,
        "endTime":1574127724519,
        "roleName":"abcdef",
        "startFlag":""
    }
    


    3.6.6 响应结果

    • 响应数据格式: JSON
      • 响应头为:Content-Type:application/json
    名称 类型 描述
    code Integer 响应码,正常情况时为200,异常时,见附录 响应码定义
    msg String 响应码说明,正常时返回ok,异常时,见附录 响应码定义
    data SimuClickData 调用成功时会有该字段返回,该字段的数据结构,见SimuClickData数据结构
    • SimuClickData数据结构如下:
    名称 类型 描述
    size Integer 本次返回记录数
    startFlag String 用于分页查询的关联标记。如果返回数据中startFlag值不为""空字符串,表示需要分页查询,后续分页查询的请求参数startFlag使用该返回值填充,其他字段保持不变。如果返回的startFlag为""空字符串,表示不需要分页查询。
    details Array<SimuClickDetailMsg> 查询到的数据, 每条数据类型,见SimuClickDetailMsg数据结构
    • SimuClickDetailMsg数据结构如下:
    名称 类型 描述
    deviceId String 设备ID
    account String 角色账户
    roleName String 角色名称
    roleId String 角色ID
    clickStartTime String 点击操作开始时间,时间格式:yyyy-MM-dd HH:mm:ss
    clickStopTime String 点击操作结束时间,时间格式:yyyy-MM-dd HH:mm:ss
    imgDownloadURL String 证据图片访问链接(链接失效时间30天)
    serverName String 服务器名称
    ip String IP地址
    matchedRiskNamesList Array<RiskTag> 匹配到的风险标签列表,每条数据类型,见RiskTag数据结构
    • RiskTag数据结构如下:
    名称 类型 描述
    tag1Name String 一级标签名称
    tag2Name String 二级标签名称
    tag3Name String 三级标签名称


    3.6.7 响应数据示例:

    • 正常数据示例
    { 
    	"code": 200,
    	"msg": "ok",
    	"data": {
    		"size": 10000, 
    		"startFlag": "dfa125ga21gfa1f2adga2", 
    		"details":[
    			{
    				"appId": "xxx",
    				"deviceId": "xxxx",
    				...,
    				"matchedRiskNamesList":[
    					{
    						"tag1Name": "xxx",
    						"tag2Name": "xxx",
    						"tag3Name": "xxx"
    					},
    					...
    				]
    			}, 
    			{
    				"appId": "xxx",
    				"deviceId": "xxxx",
    				...,
    				"matchedRiskNamesList":[
    					{
    						"tag1Name": "xxx",
    						"tag2Name": "xxx",
    						"tag3Name": "xxx"
    					},
    					...
    				]
    			},
    			...
    		]
    	} 
    }
    
    • 异常数据示例
    {  
        "msg": "未授权或者授权已过期",  
        "code": 401 
    } 
    


    附录

    响应码定义

    状态码 返回信息 说明
    200 OK 正常
    400 BAD_REQUEST 请求参数不合法
    4400 API_REQ_PARA_MISSING 参数appId缺失
    4001 QUERY_TIME_LIMIT_EXCEED 查询时间超出跨度
    401 API_REQ_UNAUTHORIZED 未授权或者授权已过期
    402 OFFLINE 服务下线
    403 FORBIDDEN 无权限操作
    404 API_NOT_FOUND 服务不存在
    405 LENGTH_OVERLIMIT 长度超过限制
    406 ENTITY_TOO_LARGE 请求实体数据大小超过限制!
    407 REQUEST_EXPIRED 请求过期
    411 CAPCITY_EXCEED 请求频率或数量超过限制!
    500 SERVICE_UNAVAILABLE 服务异常
    501 SERVICE_FAILED 操作失败
    5503 API_NOT_AVAILABLE API未开放,不可使用
    5509 API_QPS_LIMIT_EXCEED API QPS超出限制
    5709 API_APP_FREQ_MIN_LIMIT_EXCEED API 最小请求频率超出限制,需要降低请求频率

    认证参数token生成说明

    接口使用签名方式进行认证,每一次请求都必须包含签名信息(即参数token),以验证用户身份,防止信息被恶意篡改。具体使用步骤如下。

    (1) 申请安全凭证

    使用 API 之前,从【易盾官网-服务管理-已开通业务】页面获取appId和appkey。请妥善保管,避免泄漏。

    (2) 生成签名参数token

    • 步骤一:将公共参数,按照参数名ASCII码表升序顺序排序。如参数:foo=1, bar=2,foo_bar=3, baz=4 。排序后的顺序是 bar=2, baz=4, foo=1, foobar=3。
    • 步骤二:将排序好的参数名参数值对,拼装成字符串,格式为:key1value1key2value2…。根据上面示例结果为:bar2baz4foo1foobar3 。
    • 步骤三:将安全凭证的appkey,加到上一步拼装的参数字符串之后。
    • 步骤四:把步骤三的字符串,采用 UTF-8 编码,使用 MD5算法(128位长度)对字符串进行摘要计算,得到token参数值(32位十六进制字符串)。
    • 代码示例
    
    String token= SignatureUtils.genSignature(appKey, appId, timestamp, nonce);
    其中:SignatureUtils.java 如下:
    
    package com.netease.is.clientapi.utils;
    import com.google.common.collect.Maps;
    import org.apache.commons.codec.digest.DigestUtils;
    import java.io.UnsupportedEncodingException;
    import java.util.Arrays;
    import java.util.Map;
    /**
    * Created by yubaohong on 19-5-22.
      */
      public class SignatureUtils {
         /**
         * 暴露获取token的方法
         * @param appKey
         * @param appId
         * @param timestamp
         * @param nonce
         * @return
         * @throws UnsupportedEncodingException
            */
    
          public static String genSignature(String appKey, String appId, String timestamp, String nonce) throws UnsupportedEncodingException {
            Map<String, String>userParams = getTokenParams(appId, timestamp, nonce);
            return SignatureUtils.genSignature(appKey, userParams);
          }
    
         /**
         * 生成签名信息
         * @param appKey产品私钥
         * @param params 接口请求参数名和参数值map,不包括signature参数名
         * @return
            */
    
          private static String genSignature(String appKey, Map<String, String> params) throws UnsupportedEncodingException {
            // 1. 参数名按照ASCII码表升序排序
            String[] keys = params.keySet().toArray(new String[0]);
            Arrays.sort(keys);
            // 2. 按照排序拼接参数名与参数值
            StringBuilder sb = new StringBuilder();
            for (String key : keys) {
                sb.append(key).append(params.get(key));
            }
            // 3. 将appKey拼接到最后
            sb.append(appKey);
            // 4. MD5是128位长度的摘要算法,转换为十六进制之后长度为32字符
            return DigestUtils.md5Hex(sb.toString().getBytes("UTF-8"));
          }
    
        /**
         * 拼接参数
         * @param appId
         * @param timestamp
         * @param nonce
         * @return
            */
    
          private static Map<String, String> getTokenParams(String appId, String timestamp, String nonce) {
            <String, String> userParams = Maps.newHashMap();
            userParams.put("appId", appId);// 固定
            userParams.put("timestamp", timestamp);
            userParams.put("nonce", nonce);
            return userParams;
          }
      }
    
    
    Online Chat Tel:95163223