样本上传接口文档

本文档介绍如何对接风险识别样本管理能力,通过API上传黑/白样本,实现样本的统一管理和维护。

1.对接准备

建议您为阿里云账号创建子账号、并通过子账号的AccessKeyID、AccessKeySecret来实现接口调用,便于后续管理。具体步骤包括:

  1. 登录RAM访问控制

  2. 身份管理-用户-创建用户;

  3. 点击该用户,选择创建AccessKeyID;

  4. 添加权限,搜索AliyunYundunSAFFullAccess并添加;

2.通过服务端SDK接入

在调用风险识别服务时,建议您使用阿里云风险识别SDK。调用方无需关注签名验证以及Body格式构建等繁琐的事情,目前支持JAVA、Python、PHP、C#、Golang、Node.js、Ruby7SDK。

JAVA Maven依赖

<dependencies>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>safconsole20210112</artifactId>
        <version>1.0.1</version>
    </dependency>
</dependencies>

代码示例

public class ApiTest {
    public static void main(String[] a) throws Exception {
        /**
         * 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
         * 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
         * 本示例通过从环境变量中读取账号的RAM用户AccessKey,来实现API访问的身份验证。运行本示例代码前,请确认配置这两个环境变量:ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET。
         */

        // RAM账号的AccessKey ID
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        // RAM账号Access Key Secret
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // 必填,您的 AccessKey ID
                .setAccessKeyId(accessKeyId)
                // 必填,您的 AccessKey Secret
                .setAccessKeySecret(accessKeySecret);
        config.endpoint = "safconsole.cn-shanghai.aliyuncs.com";
        com.aliyun.safconsole20210112.Client client = new Client(config);

        //生成访问代码,字段含义参考接口参数说明。
        String dataType = "ip";
        String dataValue = "[\"123.xxx.xxx.xxx\",\"123.xxx.xxx.xxx\"]";
        String sampleType = "block";
        String service = "account_abuse,coupon_abuse,account_takeover";
        UploadSampleApiRequest request = new UploadSampleApiRequest();
        request.setDataType(dataType);
        request.setDataValue(dataValue);
        request.setSampleType(sampleType);
        request.setService(service);

        UploadSampleApiResponse response = client.uploadSampleApi(request);
        System.out.println("httpResponse:" + JSONObject.toJSONString(response));

        //访问失败,检查和pop网关的连接是否正常
        if (response.statusCode != 200) {
            //错误处理
            System.out.println("网关错误");
            return;
        }

        //请求后端错误,按照api手册处理
        if (!"200".equals(response.body.code) || !"true".equals(response.body.success)) {
            System.out.println("请求后端错误,按照api手册处理");
            System.out.println(response.body.message);
            return;
        }

        //请求成功
        System.out.println("请求成功");
        return;

    }
}

3.接口参数说明

3.1接口入参

参数名称

参数位置

类型

是否必填

描述

示例值

SampleType

query

string

样本的类型

  • 黑名单:block

  • 白名单:pass

block

DataType

query

string

样本的数据类型

  • 手机号:mobile

  • 手机号MD5:mobileMd5

  • IP:ip

  • 设备唯一id:umid

  • 账号:accountId

  • imei:imei

  • imeiMd5:imeiMd5

  • oaid:oaid

  • oaidMd5:oaidMd5

  • androidId:androidId

  • androidIdMd5:androidIdMd5

ip

Service

query

string

生效服务的列表,多个服务用逗号分开

  • 注册风险识别基础版/增强版:account_abuse

  • 营销风险识别基础版/增强版:coupon_abuse

  • 登录风险识别基础版/增强版:account_takeover

account_abuse,coupon_abuse,account_takeover

DataValue

query

string

样本的具体值,以JSON格式传入。一次不要超过1000条。

["123.xxx.xxx.xxx","123.xxx.xxx.xxx"]

3.2接口出参

参数名称

参数位置

类型

描述

成功时的返回

statusCode

response

int

访问网关的status

200

code

response.body

string

后端返回的code

200

success

response.body

string

返回是否成功

true

msg

response.body

string

错误信息

成功时不返回

3.3返回码说明

用户发送的每次接口调用请求,无论成功与否,阿里云都会为客户返回公共参数,其中code为请求状态码。

错误代码

错误信息

说明

1101

system error

系统错误,联系阿里云进行排查

1002

userId is not null

无法获取有效的userID,请检查AK

Service parse to string list failed

Service解析失败,检查service是否符合接口格式

Service not in enum list

service不在枚举值中,检查service是否在枚举值中

SampleType is not null

SampleType为空,检查SampleType的值

SampleType not in enum list

SampleType不在枚举值中,检查SampleType是否在枚举值中

DataType is not null

DataType为空,检查DataType的值

DataType not in enum list

DataType不在枚举值中,检查DataType是否在枚举值中

DataValue is not json string

DataValue不是jsonString格式,请检查DataValue

DataValue is empty

DataValue为空,请检查DataValue数量

DataValue size larger than 1000

DataValue一次上传超过1000条,请检查DataValue数量

注意:接口QPS设置需小于等于50。