最近更新时间:2024-12-27 16:34:49
KS3Client 是 KS3 服务的 Android 客户端,它为调用者提供了一系列的方法进行操作、管理存储空间(Bucket)和文件(Object)等。在使用 SDK 发起对 KS3 的请求前,您需要初始化一个 KS3Client 实例,并对它进行一些必要设置。
移动终端是一个不受信任的环境,把 AccessKeyId
和 AccessKeySecret
直接保存在终端用来加签请求,存在极高的风险。推荐使用 自签名模式,可根据需要选择下列两种方式中的一种:
a. 直接利用AccessKey、SecretKey初始化(不安全,仅建议测试时使用)
// 创建KS3Client实例,AccessKeyId和SecretAccessKey可以在ks3控制台上获取
Ks3Client client = new Ks3Client("AccessKeyId", "SecretAccessKey", getApplicationContext());
// 设置您访问Bucket所在地域对应的Endpoint。以北京为例,Endpoint填写为ks3-cn-beijing.ksyuncs.com
client.setEndpoint("ks3-cn-beijing.ksyuncs.com");
// 默认配置,可根据需要修改,如果不设置,会有默认配置。
Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();
// 使用https
// 若遇到java.net.UnknownServiceException: CLEARTEXT communication to ks3-cn-beijing.ksyuncs.com not permitted by network security policy错误,可通过设置该配置解决
configuration.isHttps(true);
// 设置config配置
client.setConfiguration(configuration);
b. 实现授权回调(AuthListener)获取Token(推荐使用)
Ks3Client client = new Ks3Client(new AuthListener() {
@Override
public String onCalculateAuth(String httpMethod,
String ContentType, String Date, String ContentMD5,
String Resource, String Headers) {
// 此处应由APP端向业务服务器发送post请求返回Token。
// 需要注意该回调方法运行在非主线程
String token = requsetToAppServer(httpMethod, ContentType,
Date, ContentMD5, Resource, Headers);
return token;
}
}, Activity.this);
// 配置类如果不设置,会有默认配置。
Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();
client.setConfiguration(configuration);
client.setEndpoint("ks3-cn-beijing.ksyuncs.com");
onCalculateAuth()回调方法参数说明:
Content-MD5 表示请求内容数据的MD5值, 使用Base64编码
Content-Type 表示请求内容的类型
Date 表示此次操作的时间,且必须为 HTTP1.1 中支持的 GMT 格式,客户端应 务必 保证本地时间正确性
CanonicalizedKssHeaders 表示HTTP请求中的以x-kss开头的Header组合
CanonicalizedResource 表示用户访问的资源
关于授权回调的必要说明:
对于使用AuthListener以Token方式初始化SDK的用户,需要注意onCalculateAuth()回调方法中的参数,为计算签名的参数,服务器端应根据签名生成规则,利用AccessKeyID及AccessKeySecret 计算出签名并正确返回给SDK。
onCalculateAuth()回调方法的参数Content-MD5, Content-Type, CanonicalizedKssHeaders参数 可为空。若为空,则SDK会使用空字符串("")替代, 但Date和CanonicalizedResource不能为空。
为保证请求时间的一致性,需要App客户端及客户业务服务器保证各自的时间正确性,否则用 错误的时间 尝试请求,会返回403Forbidden错误。
也可以在初始化的时候设置详细的KS3ClientConfiguration:
Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();
// 设置http超时时长, 默认20000
configuration.setConnectionTimeout(20000);
// 设置socket超时时长,默认50000
configuration.setSocketTimeout(50000);
// 设置最大连接数,默认10
configuration.setMaxConnections(10);
// 设置代理host
configuration.setProxyHost(null);
// 设置代理用户名
configuration.setProxyUsername(null);
// 设置密码
configuration.setProxyPassword(null);
// 设置代理端口
configuration.setProxyPort(-1);
// 设置最大重连次数
configuration.setMaxRetrytime(0);
// 设置重连超时时长,默认5000
configuration.setRetryTimeOut(5000);
client.setConfiguration(configuration);
Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();
// 设置自定义 user-agent, 默认使用'ks3-android-sdk'
configuration.setUserAgent("customUserAgent");
考虑到移动端开发场景下不允许在UI线程执行网络请求的编程规范,SDK大多数接口都提供了同步、异步两种调用方式,同步接口调用后会阻塞等待结果返回,而异步接口需要在请求时传入回调函数,请求的执行结果将在回调中处理。
同步接口不能在UI线程调用。遇到异常时,将直接抛出Ks3ClientException
或者Ks3ServiceException
异常,前者指本地遇到的异常如网络异常、参数非法等;后者指KS3返回的服务异常,如鉴权失败、服务器错误等。
异步请求遇到异常时,异常会在回调函数中处理。
纯净模式