初始化（Android）

KS3Client 是 KS3 服务的 Android 客户端，它为调用者提供了一系列的方法进行操作、管理存储空间（Bucket）和文件（Object）等。在使用 SDK 发起对 KS3 的请求前，您需要初始化一个 KS3Client 实例，并对它进行一些必要设置。

设置Client

移动终端是一个不受信任的环境，把 AccessKeyId 和 AccessKeySecret 直接保存在终端用来加签请求，存在极高的风险。推荐使用 自签名模式，可根据需要选择下列两种方式中的一种：

• a. 直接利用AccessKey、SecretKey初始化（不安全,仅建议测试时使用）

// 初始化客户端认证信息，需要填写相应 ak、sk、endPoint
String ak = "***";
String sk = "***";

// 创建客户端对象
Ks3Client client = new Ks3Client(ak, sk, Activity.this);

// 设置Endpoint
ks3Client.setEndpoint("ks3-cn-beijing.ksyuncs.com");

// 配置类如果不设置，会有默认配置。
Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();

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

设置自定义user-agent

Ks3ClientConfiguration configuration = Ks3ClientConfiguration.getDefaultConfiguration();

// 设置自定义 user-agent, 默认使用'ks3-android-sdk'
configuration.setUserAgent("customUserAgent"); 

对 SDK 中同步接口、异步接口的一些说明

• 考虑到移动端开发场景下不允许在UI线程执行网络请求的编程规范，SDK大多数接口都提供了同步、异步两种调用方式，同步接口调用后会阻塞等待结果返回，而异步接口需要在请求时传入回调函数，请求的执行结果将在回调中处理。

• 同步接口不能在UI线程调用。遇到异常时，将直接抛出KS3ClientException或者KS3Error异常，前者指本地遇到的异常如网络异常、参数非法等；后者指KS3返回的服务异常，如鉴权失败、服务器错误等。

• 异步请求遇到异常时，异常会在回调函数中处理。

• 业务服务器计算签名方式