OSSClient 是 OSS 服务的 Android 客户端,它为调用者提供了一系列的方法,可以用来操作,管理存储空间(bucket)和文件(object)等。在使用 SDK 发起对 OSS 的请求前,您需要初始化一个 OSSClient 实例,并对它进行一些必要设置。

说明 生命周期和应用生命周期保持一致即可。在应用启动时创建一个全局的ossclient,在应用结束时销毁即可。

确定 Endpoint

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

Endpoint类型 解释
OSS区域地址 使用OSS Bucket所在区域地址,各个区域Endpoint参考这里
用户自定义域名 用户自定义域名,且CNAME指向OSS域名

关于Endpoint,可以参考:点击查看

  • OSS区域地址

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

    • 查询Endpoint与区域对应关系详情,可以参考:点击查看
    • 您可以登录 阿里云OSS控制台,进入Bucket概览页,Bucket域名的后缀部分:如bucket-1.oss-cn-hangzhou.aliyuncs.comoss-cn-hangzhou.aliyuncs.com部分为该Bucket的外网Endpoint。
  • Cname

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

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

  • 设置EndPoint和凭证

    移动终端是一个不受信任的环境,把AccessKeyIdAccessKeySecret直接保存在终端用来加签请求,存在极高的风险。推荐使用STS鉴权模式自签名模式,详细请参考:访问控制移动端直传

    说明 如果用STS鉴权模式,推荐使用OSSAuthCredentialsProvider方式直接访问鉴权应用服务器,token过期后可以自动更新。

    更多信息可查看可查看sample点击查看

    设置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使用之前进行初始化,调用如下方法即可。

    说明
    • 日志文件内置sd卡路径\OSSLog\logs.csv。
    • 您可以自行选择将文件上传至服务器,进一步追踪问题。
    • 您还可以接入阿里云SLS日志服务进行日志文件上传,详情请参考日志服务传送门
    //日志的样式
    //通过调用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");