OSSClient 是 OSS 服务的 Android 客户端,它为调用者提供了一系列的方法进行操作、管理存储空间(Bucket)和文件(Object)等。在使用 SDK 发起对 OSS 的请求前,您需要初始化一个 OSSClient 实例,并对它进行一些必要设置。
确定Endpoint
Endpoint是阿里云OSS服务在各个区域的地址,目前支持两种形式:
- OSS区域地址
使用OSS Bucket所在区域地址时,您可以通过以下方式查询Endpoint:
- 关于Endpoint与Region对应关系的更多信息,请参见访问域名和数据中心。
- 您可以登录阿里云OSS管理控制台,进入Bucket 概览页,Bucket域名
examplebucket.oss-cn-hangzhou.aliyuncs.com
的后缀部分oss-cn-hangzhou.aliyuncs.com
,即为该Bucket的外网Endpoint。
- 自定义域名
通过CNAME将自定义域名绑定到某个Bucket上,然后通过该域名访问Bucket内的文件。
假设您要将自定义域名
example.aliyundoc.com
绑定到华东1(杭州)地域名为examplebucket的存储空间。您需要到您的域名aliyundoc.com
托管商处设定一个新的域名解析,并将https://example.aliyundoc.com
解析到https://examplebucket.oss-cn-hangzhou.aliyuncs.com
,类型为CNAME。
设置EndPoint和凭证
移动终端是一个不受信任的环境,把AccessKeyId
和AccessKeySecret
直接保存在终端用来加签请求,存在极高的风险。推荐使用STS鉴权模式或自签名模式。
关于STS鉴权模式以及自签名模式的更多信息,请参见授权访问。
关于示例工程的更多信息,请参见GitHub。
设置EndPoint和CredentialProvider示例如下:
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// 填写STS应用服务器地址。
String stsServer = "https://example.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 = "https://example.aliyundoc.com";
...
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
启用日志
移动端的使用环境比较复杂。会出现部分区域或某一个时段无法正常使用OSS SDK的情况。为了进一步方便开发者定位问题,OSS SDK在开启日志记录功能后,会将一些LOG信息记录在本地。如需开启需要在OSSClient使用之前进行初始化,调用方法如下。
// 日志的样式。
// 通过调用OSSLog.enableLog()开启可以在控制台查看日志。
// 支持在手机内置sd卡路径\OSSLog\logs.csv下写入日志文件,默认不开启。
// 日志会记录OSS操作行为中的请求数据、返回数据、异常信息。
// 例如requestId、response header等。
// 以下为日志记录示例。
// Android版本。
// android_version:5.1
// Android手机型号。
// mobile_model:XT1085
// 网络状况。
// 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);
同步接口和异步接口说明
考虑到移动端开发场景下不允许在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,表示开启DNS配置。如需关闭请将其设置为false。
设置自定义user-agent
ClientConfiguration conf = new ClientConfiguration();
//设置的user-agent会默认添加到SDK配置的user-agent末尾。
conf.setUserAgentMark("customUserAgent");