确定 Endpoint

Endpoint 是阿里云 OSS 服务在各个区域的地址，目前支持以下两种形式：

• OSS区域地址

  使用OSS Bucket所在区域地址，Endpoint查询可以有下面两种方式：

  • 查询Endpoint与区域对应关系详情请参见：访问域名和数据中心。
  • 您可以登录 阿里云OSS控制台，进入Bucket概览页，Bucket域名的后缀部分：如bucket-1.oss-cn-hangzhou.aliyuncs.com的oss-cn-hangzhou.aliyuncs.com部分为该Bucket的外网Endpoint。
• Cname

  您可以将自己拥有的域名通过Cname绑定到某个存储空间上，然后通过自身域名访问存储空间内的文件。

  比如您要将域名new-image.xxxxx.com绑定到深圳区域的名称为image的存储空间上：您需要到您域名xxxxx.com托管商那里设定一个新的域名解析，将http://new-image.xxxxx.com 解析到 http://image.oss-cn-shenzhen.aliyuncs.com ，类型为CNAME。

设置EndPoint和凭证

移动终端是一个不受信任的环境，把AccessKeyId和AccessKeySecret直接保存在终端用来加签请求，存在极高的风险。推荐使用STS鉴权模式或自签名模式，详情请参见：授权访问、 快速搭建移动应用直传服务。

关于示例工程更多信息请参见GitHub。

设置EndPoint和CredentialProvider示例如下：

String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";

String stsServer = "STS应用服务器地址，例如http://abc.com"
// 推荐使用OSSAuthCredentialsProvider。token过期可以及时更新。
OSSCredentialProvider credentialProvider = new OSSAuthCredentialsProvider(stsServer);

// 配置类如果不设置，会有默认配置。
ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // 连接超时，默认15秒。
conf.setSocketTimeout(15 * 1000); // socket超时，默认15秒。
conf.setMaxConcurrentRequest(5); // 最大并发请求数，默认5个。
conf.setMaxErrorRetry(2); // 失败后最大重试次数，默认2次。

OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

设置EndPoint为cname

如果您已经在Bucket上绑定cname，将该cname直接设置到endpoint即可。如：

String endpoint = "http://new-image.xxxxx.com";
...
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

启用日志

移动端的使用环境比较复杂。会出现部分区域或某一个时段无法正常使用OSS SDK的情况。为了进一步方便开发者定位问题，OSS SDK在开启日志记录功能后，会将一些LOG信息记录在本地。如需开启需要在OSSClient使用之前进行初始化，调用方法如下。

//日志的样式
//通过调用OSSLog.enableLog()开启可以在控制台看到日志，
//并且会支持写入手机sd卡中的一份日志文件位置在内置sd卡路径\OSSLog\logs.csv  默认不开启
//日志会记录oss操作行为中的请求数据，返回数据，异常信息
//例如requestId,response header等，下边是一个日志记录case
//android_version：5.1  android版本
//mobile_model：XT1085  android手机型号
//network_state：connected  网络状况
//network_type：WIFI 网络连接类型
//具体的操作行为信息:
//[2017-09-05 16:54:52] - Encounter local execpiton: //java.lang.IllegalArgumentException: The bucket name is invalid. 
//A bucket name must: 
//1) be comprised of lower-case characters, numbers or dash(-); 
//2) start with lower case or numbers; 
//3) be between 3-63 characters long. 
//------>end of log
OSSLog.enableLog();  //调用此方法即可开启日志

设置网络参数

也可以在初始化的时候设置详细的ClientConfiguration：

String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";

// 在移动端建议使用STS的方式初始化OSSClient。
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");


ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // 连接超时，默认15秒。
conf.setSocketTimeout(15 * 1000); // socket超时，默认15秒。
conf.setMaxConcurrentRequest(5); // 最大并发请求书，默认5个。
conf.setMaxErrorRetry(2); // 失败后最大重试次数，默认2次。

OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);

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

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

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

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

调用异步接口时，函数会直接返回一个Task，Task可以取消、等待直到完成、或者直接获取结果。如：

OSSAsyncTask task = oss.asyncGetObejct(...);
task.cancel(); // 可以取消任务
task.waitUntilFinished(); // 等待直到任务完成
GetObjectResult result = task.getResult(); // 阻塞等待结果返回

设置是否开启DNS配置

ClientConfiguration conf = new ClientConfiguration();
conf.setHttpDnsEnable(true);//默认为true 表开启，需要关闭可以设置为false。

设置自定义user-agent

ClientConfiguration conf = new ClientConfiguration();
//设置的ua会默认添加到sdk默认ua的最后边，取得时候自行去取最后一个。
conf.setUserAgentMark("customUserAgent");