举报系统接入文档

通过openApi上报举报数据,由易盾给出被举报方的相关验证信息

通用设置

  • 通信协议

支持HTTP协议,HTTPS协议

  • 请求方法

Post方法

  • 字符编码

所有接口的请求和响应数据编码皆为utf-8

  • API请求结构
名称描述备注
API入口具体API接口地址http://open-yb.163yun.com/api/open/v1/risk/doubtful/checkroleidexist
公共参数每个接口都包含的通用参数详见 公共参数 说明
私有参数每个接口特有的参数详见每个API接口定义
  • 公共参数

公共参数是用于标识产品和接口鉴权目的的参数,如非必要,在每个接口单独的接口文档中不再对这些参数进行说明,每次请求均需要携带这些参数。

  • 鉴权参数
鉴权参数名称类型是否必填最大长度描述
appIdString10appId
timestamplong13调用接口当前时间,单位毫秒,防重放
nonceString16随机码,防重放
tokenString32使用appKey签名的数据,检验权限
  • 响应通用字段

Json 格式, 如无特殊说明,每次请求的返回值中,都包含下面字段:

参数名称类型描述
codeint接口调用状态,200:正常,其他值:调用出错,返回码见响应返回码定义
msgString结果说明,成功返回ok,调用出错,那么返回错误描述见响应返回码定义
dataJSON返回结果,构成如下
lastestEventTimelong不为默认值0时为当前可供查询数据的最新时间

注意:嫌疑数据明细查询返回格式比较特殊,请具体接口定义。

  • 响应返回码

响应返回码(code)反应了API 调用和执行的概要结果。当返回码不为 200 时, 表示请求未正常执行,返回码描述 (msg) 对该结果进行了细化补充,用户可根据返回码判断 API 的执行情况。

所有接口调用返回值均包含 code 和 msg 字段, code 为返回码值,msg 为返回码描述信息,返回码表如下:

200OK正常
400BAD_REQUEST请求参数不合法
4400API_REQ_PARA_MISSING参数appId缺失
401API_REQ_UNAUTHORIZED未授权或者授权已过期
402OFFLINE服务下线
403FORBIDDEN无权限操作
404API_NOT_FOUND服务不存在
405LENGTH_OVERLIMIT长度超过限制
406ENTITY_TOO_LARGE请求实体数据大小超过限制!
407REQUEST_EXPIRED请求过期
411CAPCITY_EXCEED请求频率或数量超过限制!
500SERVICE_UNAVAILABLE服务异常
501SERVICE_FAILED操作失败
5503API_NOT_AVAILABLEAPI未开放,不可使用
5509API_QPS_LIMIT_EXCEEDAPI QPS超出限制
5709API_APP_FREQ_MIN_LIMIT_EXCEEDAPI 最小请求频率超出限制,需要降低请求频率
  • 接口鉴权

易盾移动安全服务使用签名方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature 参数),以验证用户身份,防止信息被恶意篡改。

1.申请安全凭证

在第一次使用 API 之前,需申请安全凭证,Appkey,请妥善保管,避免泄漏。

2.签名生成算法

签名生成方法如下:

a.对公有参数,按照参数名ASCII码表升序顺序排序。如:foo=1, bar=2, foo_bar=3, baz=4 排序后的顺序是 bar=2, baz=4, foo=1, foobar=3。

b.将排序好的参数名和参数值构造成字符串,格式为:key1+value1+key2+value2… 。根据上面的示例得到的构造结果为:bar2baz4foo1foobar3 。

c.选择申请的Appkey,加到上一步构造好的参数字符串之后。

d.把c步骤拼装好的字符串采用 utf-8 编码,使用 MD5 算法对字符串进行摘要,计算得到 signature 参数值,将其加入到接口请求参数中即可。MD5 是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32位十六进制字符。

获取签名Token示例代码如下:

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;
    }
}

举报详情上报

接口地址: http://open-yb.163yun.com/api/open/v1/risk/report

请求方法:Post

接口描述:举报数据上报

Content-Type:application/json

请求参数,由鉴权参数与请求参数两部分构成:

公共参数已省略,详细见 请求公共参数 请求参数定义如下:

参数名称类型长度是否必填描述
appIdstring10AppID
reportTypeint1举报类型.0:外挂,1:工作室,2:言语辱骂,3:违规宣传,4:消极游戏
reportTimelong13举报时间
reportRoleAccountstring最大255举报用户账号
reportRoleIdstring最大255举报用户角色Id
reportRoleNamestring最大255举报用户角色名
reportDeviceIdstring最大255举报用户设备标识
reportDescstring最大255举报描述
verificationSpanint2查询跨度,以小时为单位,建议最大为24小时
reportedRoleAccountstring最大255被举报用户账号
reportedRoleIdstring最大255被举报用户角色
reportedRoleNameString最大255被举报用户名称
reportedRoleServerString最大255被举报用户服务器
reportedDeviceIdstring最大255被举报用户设备标识
reportedPlatformint2被举报方系统 1:ios ; 2:andorid

举报详情查询

接口地址: http://open-yb.163yun.com/api/open/v1/risk/report/list

请求方法:Post

接口描述:举报详情数据查询

Content-Type:application/json

请求参数,由鉴权参数与请求参数两部分构成:

公共参数已省略,详细见 请求公共参数

请求参数定义如下:

参数名称类型长度是否必填描述
startTimelong13举报时间查询起始时间
endTimelong13举报时间查询终止时间
reportedRoleAccountString最大255被举报方账号
reportedRoleNameString最大255被举报方角色名
reportedRoleIdsArray最大65535被举报方角色ID
reportedRoleServerString最大255被举报用户服务器
reportedDeviceIdString最大255被举报方设备ID
reportRoleAccountString最大255举报方账号
reportRoleNameString最大255举报方角色名
reportRoleIdString最大255举报方角色ID
reportDeviceIdString最大255举报方设备ID
defineResultint1风险处理结果(1:拦截成功;0:未拦截)

请求参数示例:

{"appId":"xxx888871","timestamp":${currentTime},"token":"${sign}","nonce":"111","startTime":1564041324000,"endTime":1574127724519}

响应结果:

调用正常返回使用linedText格式

响应内容设置:Content-type: text/plain;charset=utf-8

linedText格式定义如下:

行号格式描述
第1行startFlag=${下一批数据起始标记}1. 当查询需要分批返回数据时,表示下一批数据起始标记。
2. 当为null值,表示数据都已经返回,不需要继续执行下一批查询
第2行separator=${列分隔符号}行中的不同列之间分隔符,如Tab,或\001等
第3行colums=${数据列名称}数据列名称,以"列分隔符"切分
第4行size=${总行数}数据总行数,可以为空值
第5行每行数据记录数据记录,从第5行开始
第...行......

返回示例如下:

startFlag=949f4284bb294e7c840cc535143fc5a6
separator=\t
colums=举报时间	举报账号	举报角色ID	举报角色名称	被举报账号	被举报角色ID	被举报角色名称	被举报角色服务器	举报类型	验证结果	外挂检测	风险检测	应用环境检测	威胁等级	风险处理	查询跨度
size=1
1595223901000	roleaccount007	JB_QA_RoI	null	roleaccount007	roleTestid98	yltestRN	江湖3	工作室	-1	未发现	未发现	未发现	1	-1	24

异常返回Json格式,构成如下:

参数名称类型描述
codeint接口调用状态,200:正常,其他值:调用出错,返回码见响应返回码定义
msgString结果说明,成功返回ok,调用出错,那么返回错误描述见响应返回码定义

示例如下:

{
    "code": 4401,
    "msg": "Token验证失败"
}