本文档介绍如何对接风险识别样本管理能力,通过API上传黑/白样本,实现样本的统一管理和维护。
1.对接准备
建议您为阿里云账号创建子账号、并通过子账号的AccessKeyID、AccessKeySecret来实现接口调用,便于后续管理。具体步骤包括:
登录RAM访问控制;
身份管理-用户-创建用户;
点击该用户,选择创建AccessKeyID;
添加权限,搜索AliyunYundunSAFFullAccess并添加;
2.通过服务端SDK接入
在调用风险识别服务时,建议您使用阿里云风险识别SDK。调用方无需关注签名验证以及Body格式构建等繁琐的事情,目前支持JAVA、Python、PHP、C#、Golang、Node.js、Ruby共7种SDK。
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 |
DataType | query | string | 是 | 样本的数据类型
| ip |
Service | query | string | 是 | 生效服务的列表,多个服务用逗号分开
| 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。