# SDK调用
该章节介绍SDK调用
# 1.SDK调用
客户端可通过SDK向BFTAgent发送文件和接收文件，通过控制管理中心定义客户端，客户端通过BFTServer获取Token，在传输文件前在BFTAgent中进行Token校验，通过校验可与BFTAgent进行文件发送、接收操作；文件传输日志通过BFTAgent上传到日志中心
# 2.SDK使用前环境准备
操作前提说明：
1：准备一个BFTAgent，并开启客户端功能
2：BFTAgent启动且正常登陆BFTServer管理节点
3：在BFTConsole控制管理中心配置BFTAgent白名单
4：新建一个SDK项目
# 2.1 客户端token有效时长
默认在BFTServer获取的客户端Token有效期为24小时，超过有效期后需要重新申请，否则无法通过客户端认证。
Token认证有效时长可自行定义，{BFTServer安装目录}/bftserver/config/bft-server-config.xml内修改<resource/TockenDuration> 默认值 86400000 （24小时）单位：秒，修改后需要重启BFTServer。
# 2.2 BFTAgent准备
解压Primeton_BFT_7.6.0_Agent安装包。
修改bftagent/config/bft-agent-config.xml配置文件。
| 配置项 | 备注 |
|---|---|
| name | BFTAgent名称，名称应该全局唯一，如果出现重名会导致启动登陆失败 |
| ip | 安装BFTAgent的机器IP |
| receiveport | BFTAgent文件传输端口 |
| httpPort | BFTAgent管理端口 |
| server | BFTServer服务器地址，BFTServer服务器地址可以填写多个用“;”分隔 |
| clientstart | 客户端功能开关；true开启，false关闭 |
| clientsocketport | 客户端通信端口 |
注意：一个机器部署多个BFTAgent需要修改receiveport，httpPort和clientsocketport防止端口冲突启动报错。
# 2.3设置客户端信息
在BFTConsole控制管理中心“服务器管理 ->客户端管理”配置客户端信息
| 字段名称 | 说明 |
|---|---|
| 名称 | 客户端名称 |
| 密码 | 客户端密码 |
| 有效开始时间 | 客户端有效开始时间，未在有效期内无法使用客户端传输文件 |
| 有效截止时间 | 客户端有效开始时间，未在有效期内无法使用客户端传输文件 |
| 状态 | 正常/挂起 正常状态下客户端可用 |
| 描述 | 描述 |
| 关联代理 | 客户端传输文件代理信息 |
| 使用服务器赋权 | 可用客户端地址 |
# 2.4.建立sdk项目
以java工程项目为例，新建SDKTest。
说明：系统jdk请使用jdk1.8
将sdklib.zip压缩包内的jar引入SDKTest工程。
# 3.SDK发送/接收
1、根据客户端配置信息获取token
2、代理校验token通过发送/接收文件
# 1、通过BFTserver获取token
创建token获取类(SdkTestGetToken)，使用com.primeton.transfer.sdk.TokenOperate类向BFTServer传输客户端信息进行验证，并获取客户端Token。
示例：
package com.sdk;
import com.primeton.filetransfer.agent.client.bean.ClientBean;
import com.primeton.filetransfer.common.response.TokenResult;
import com.primeton.transfer.sdk.TokenOperate;
import com.primeton.transfer.sdk.TokenOperateFactory;
/**
* TOKEN认证文件传输，第一步骤
* 通过客户端名称、密码获取认证TOKEN
*
*/
public class SdkTestGetToken {
//参数内容加密算法（SM2）公钥文件绝对路径，该文件在代理安装目录/bftagent/resource/sm2/sm2.cert.pem
private static final String publicCerPath = "{agent安装目录}\\bftagent\\resource\\sm2\\sm2.cert.pem";
public static void main(String[] args) {
//1.定义sdk信息
ClientBean clientBean = new ClientBean();
//客户端名称
clientBean.setClientName("test");
//客户端密码
clientBean.setClientPasswd("111111");
//server传输引擎地址，可以填写多个地址：127.0.0.1:6311;127.0.0.1:6312;127.0.0.1:6313
String tokenCenter = "127.0.0.1:6311";
//2.配置公钥文件路径，初始化token操作类
TokenOperate tokenOperate = TokenOperateFactory.create()
.setPublicFilePath(publicCerPath)
.setClientBean(clientBean).build();
//3.认证
TokenResult tokenResult = tokenOperate.getToken(tokenCenter);
//4.打印token获取结果
if(tokenResult.isSucceed()) {
System.out.println("认证TOKEN获取成功");
}else {
System.out.println("认证TOKEN获取失败");
}
System.out.println(tokenResult);
}
}
SDK获取客户端TOKEN相关 参数说明：
| 参数 | 说明 |
|---|---|
| clientName | 客户端名称 |
| clientPasswd | 客户端密码 |
| tokenCenter | BFTServer地址 |
| publicFilePath | Sm2本地公钥文件路径 |
客户端认证后，通过 com.primeton.filetransfer.common.response.TokenResult类的getToken函数获取结果。
# 2、发送、接收文件
package com.sdk;
import com.primeton.filetransfer.agent.client.bean.ClientBean;
import com.primeton.filetransfer.agent.client.bean.TransferResult;
import com.primeton.filetransfer.agent.util.HostsUtils;
import com.primeton.filetransfer.common.TransferPolicy;
import com.primeton.transfer.sdk.SdkOperate;
import com.primeton.transfer.sdk.SdkOperateFactory;
import java.util.ArrayList;
import java.util.List;
public class SdkTest {
public static void main(String[] args) {
//1.定义sdk信息
ClientBean clientBean = new ClientBean();
clientBean.setClientName("test");//账号
//文件接收时填需填写 客户端ip，客户端端口
clientBean.setClientIp(HostsUtils.getLocalIpInfo());//客户端所在服务器IP
clientBean.setClientPort(6631);//端口
//客户端获取的有效token，可参考 SdkTestGetToken 类获取token
String tempToken = "046c2d58b0927a7530b3936f2691b95adcc53af5314d7b80cef61bd5cb7c1c55e7142863a00b2d2806cb9c0479297291204fc933790c93bc77f856dc079e8858b21312dca2afd3ecdd97b678322b2b581f24ced8e79a53c30f94839f124f8b340d66eef97a743bb96853b6d2a3949e584b9c8da85293e706fa1a3bb0fd8c12ddd57b023e50db80a883da7952f4d48435e28aed9872e7eb4ad70126126bbbd8af82ada2feb3c97256708985d61a41e54366386328ec7c41cc377587be734fe2cd67368522377e04648e8a121c1a23963427f36dcb65ac3897a74f994a7ff842755ce6baccaf5134047985946a0fd275d68e3523fc12dab0d2b6a0518e8f56801045a280286aa94f25e0b7dbafee7fd26a97613c9326d4d3a610";
//2.初始化sdk操作类，并传入token
SdkOperate operate = SdkOperateFactory.create().setClientBean(clientBean).setToken(tempToken).build();
/**
* 3.将客户端的目录下文件全部发送到接收方接收目录，
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 发送目录
* @param recFolder 接收目录
*/
TransferResult result1 = operate.send("127.0.0.1:8666","E:\\bft76\\Guidfolder1","E:\\bft76\\Guidfolder2");
System.out.println(result1);
/**
* 4.将客户端的目录下具体文件发送到接收方接收目
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 发送目录
* @param recFolder 接收目录
* @param fileList 传输文件列表
*/
List<String> files = new ArrayList<String>();
files.add("E:\\bft76\\Guidfolder1\\fileName.file"); //文件全路径
TransferResult result2 = operate.send("127.0.0.1:8666","E:\\bft76\\Guidfolder1","E:\\bft76\\Guidfolder2",files);
System.out.println(result2);
/**
* 触发向目标方加密传输文件
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 发送目录
* @param recFolder 接收目录
* @param encryptAlgo 加密算法 des aes sm4
* @return TransferResult 接收触发结果
*/
TransferResult result21 = operate.send("127.0.0.1:8666","E:\\bft76\\Guidfolder1","E:\\bft76\\Guidfolder2","sm4");
System.out.println(result21);
/**
* 5.下载代理服务器目录下所有文件到客户端所在服务器目录
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 代理服务器发送目录
* @param recFolder SDK所在服务器接收目录
* @param fileList 传输文件列表
*/
TransferResult result3 = operate.receive("127.0.0.1:8666", "E:\\bft76\\Guidfolder1", "E:\\bft76\\Guidfolder2");
System.out.println(result3);
/**
* 5.下载代理服务器目录下指定文件到客户端所在服务器目录
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 代理服务器发送目录
* @param recFolder SDK所在服务器接收目录
* @param fileList 下载的文件列表
*/
List<String> files1 = new ArrayList<String>();
files1.add("E:\\bft76\\Guidfolder1\\fileName.file"); //文件全路径
TransferResult result4 = operate.receive("127.0.0.1:8666", "E:\\bft76\\Guidfolder1", "E:\\bft76\\Guidfolder2",files1);
System.out.println(result4);
/**
* 5.下载代理服务器目录下指定文件到客户端所在服务器目录
* @param agentAddress 接收方地址，形式 ： ip:port;ip:port
* @param sendFolder 代理服务器发送目录
* @param recFolder SDK所在服务器接收目录
* @param fileList 下载的文件列表
*/
TransferResult result5 = operate.receive("127.0.0.1:8666", "E:\\bft76\\Guidfolder1", "E:\\bft76\\Guidfolder2","sm4");
System.out.println(result5);
/**
* 全属性参数传输
*/
TransferPolicy policy = new TransferPolicy();
policy.setName("");
policy.setFileSendDir("");
policy.setFileReceiveDir("");
TransferResult result = operate.receive("127.0.0.1:8666", policy);
}
}
# 3.1 实例化文件传输操作类
文件传输操作类：com.primeton.transfer.sdk.SdkOperate
SdkOperate构造函数：
public SdkOperate(String clientName,String clientIp, int clientPort)；
| 参数 | 说明 |
|---|---|
| clientName | SDK名称(bft-client-config.xml中的/filetransfer/client/name) |
| clientIp | SDK端ip(bft-client-config.xml中的/filetransfer/client/ip) |
| clientPort | SDK文件传输端口(bft-client-config.xml中的/filetransfer/client/socketport) |
public SdkOperate(ClientBean clientBean)；
| 参数 | 说明 |
|---|---|
| clientBean | 实现类 com.primeton.filetransfer.agent.client.bean.ClientBean；记录SDK名称，IP，文件传输端口 |
# 3.2 文件发送函数
通过发送函数调用，可实现向代理服务器的发送文件。
operate.send(String agentAddress, String sendFolder, String recFolder, List fileList, boolean signal, String encryptAlgo);
| 参数 | 要求 | 说明 |
|---|---|---|
| agentAddress | 必填非空 | 接收代理服务器地址，形式 ： IP:POR bft-agent-config.xml中的/filetransfer/agent/ip bft-agent-config.xml中的/filetransfer/client/clientsocketport |
| sendFolder | 必填非空 | 发送目录 |
| recFolder | 必填非空 | 接收代理服务器接收目录 |
| fileList | 可为空 | 发送文件集合，说明：如果文件集合不为空，则以文件集合为准，发送目录无效 |
| signal | 默认false | 成功后是否在接收目录下生成一个命为signal.file的标识文件 |
| encryptAlgo | 默认no | 加密方式；no（不加密），sm4，aes，des |
# 3.3文件接收函数
operate.receive(String agentAddress, String sendFolder, String recFolder, List fileList, String encryptAlgo);
| 参数 | 要求 | 说明 |
|---|---|---|
| agentAddress | 必填非空 | 发送代理服务器地址，形式 ： IP:PORT bft-agent-config.xml中的/filetransfer/agent/ip bft-agent-config.xml中的/filetransfer/client/clientsocketport |
| sendFolder | 必填非空 | 代理服务器发送目录 |
| recFolder | 必填非空 | SDK服务器接收目录 |
| fileList | 可为空 | 获取文件集合，说明：如果文件集合不为空，则以文件集合为准，发送目录无效 |
| signal | 默认false | 成功后是否在接收目录下生成一个命为signal.file的标识文件 |
| encryptAlgo | 默认no | 加密方式；no（不加密），sm4，aes，des |
# 3.4 结果执行返回
发送/接受函数调用返回的实例都是 com.primeton.filetransfer.agent.client.bean.TransferResult；
| 属性 | 类型 | 说明 |
|---|---|---|
| result | boolean | 执行结果，true：执行成功，false执行失败 |
| totalsize | int | 文件总数 |
| succsize | int | 成功传输文件数 |
| failsize | int | 失败传输文件数 |
| onfilesize | int | 未传输文件 |
| failfilemap | Map<String, String> | 类型 Map<String, String>，传输失败文件集合，<key：文件名,value：文件路径> |
| onfilemap | Map<String, String> | 类型 Map<String, String>，未传输文件集合，<key：文件名,value：文件路径> |
| message | String | 返回消息 |
| startDate | long | 开始时间 |
| endDate | long | 结束时间 |
# 3.5 Token认证失败情况
# 3.5.1客户端名称与Token不匹配
验证时使用的客户端名称与Token不匹配。
执行结果：
执行文件传输失败,总文件数：0,成功文件数：0,失败文件数：0,未传文件数：0,消息：未通过[127.0.0.1:8666]节点认证, 失败原因: [客户端账号和使用的认证TOKEN不匹配,请设置正确认证TOKEN]
# 3.5.2Token不正确
文件传输时使用错误的Token进行验证。
执行结果：
执行文件传输失败,总文件数：0,成功文件数：0,失败文件数：0,未传文件数：0,消息：未通过[127.0.0.1:8666]节点认证, 失败原因: [认证TOKEN内容解密失败：Invalid point encoding 0x14]
# 3.5.3Token过期
文件传输时使用过期的Token进行验证。
执行文件传输失败,总文件数：0,成功文件数：0,失败文件数：0,未传文件数：0,消息：未通过[127.0.0.1:8666]节点认证, 失败原因: [认证TOKEN解析失败：JWT expired at 2023-11-08T15:38:56Z. Current time: 2023-11-08T15:39:15Z, a difference of 19844 milliseconds. Allowed clock skew: 0 milliseconds.]
# 3.5.4客户端无此代理传输权限
客户端使用没有传输代理的传输权限。
执行文件传输失败,总文件数：0,成功文件数：0,失败文件数：0,未传文件数：0,消息：未通过[127.0.0.1:8666]节点认证, 失败原因: [127client 未赋权与代理 127Agent1 传输文件权限]
# 3.5.5客户端无法连接代理服务器
由于代理服务器未启动或代理地址填写错误，客户端无法连接代理服务器。
执行文件传输失败,总文件数：0,成功文件数：0,失败文件数：0,未传文件数：0,消息：未通过[192.168.16.143:8695]节点认证, 失败原因: ['192.168.16.143:8695'连接失败]
