文档

Android初始化

更新时间:

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

说明

OSSClient的生命周期需与应用程序的生命周期保持一致。即您需要在应用启动时创建一个全局的OSSClient,在应用结束时销毁OSSClient。

初始化OSSClient

重要

移动终端是一个不受信任的环境,把AccessKeyIdAccessKeySecret直接保存在终端用来加签请求,存在极高的风险。推荐使用STS鉴权模式或自签名模式。

您可以通过以下多种方式新建OSSClient。

说明

如果需要调用接口执行上传、下载等操作,请参见快速入门

列举存储空间所使用的OSSClient初始化方式与这里示例中的通用形式不同,具体请参考列举存储空间

使用STS新建OSSClient

以下代码用于使用STS新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
String securityToken = "yourSecurityToken";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
// 创建OSSClient实例。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

使用自定义域名新建OSSClient

以下代码用于使用自定义域名新建OSSClient。

// yourEndpoint填写自定义域名。
String endpoint = "yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
String securityToken = "yourSecurityToken";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
// 创建OSSClient实例。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

专有云或专有域环境新建OSSClient

以下代码用于在专有云或专有域环境新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。
String endpoint = "yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
String securityToken = "yourSecurityToken";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration configuration = new ClientConfiguration();
// 跳过CNAME解析。
List<String> excludeList = new ArrayList<>();
excludeList.add(endpoint);
configuration.setCustomCnameExcludeList(excludeList);
// 创建OSSClient实例。
OSSClient oss = new OSSClient(getApplicationContext(),endpoint, credentialProvider, configuration);

使用自签名模式新建OSSClient

以下代码用于使用自签名模式新建OSSClient。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";

OSSCredentialProvider credentialProvider = new OSSCustomSignerCredentialProvider() {
    @Override
    public String signContent(String content) {
        // 对content进行签名,signature为签名后的字符串。
        String signature = "signature";
        return signature;
    }
};
// 创建OSSClient实例。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

关于自签名模式的更多信息,请参见自签名模式

配置OSSClient

ClientConfiguration是OSSClient的配置类,您可通过此类来配置代理、连接超时、最大连接数等参数。

参数

描述

方法

maxConcurrentRequest

最大并发数。默认为5。

ClientConfiguration.setMaxConcurrentRequest

socketTimeout

Socket层传输数据的超时时间,单位为毫秒。默认为60000毫秒。

ClientConfiguration.setSocketTimeout

connectionTimeout

建立连接的超时时间,单位为毫秒。默认为60000毫秒。

ClientConfiguration.setConnectionTimeout

max_log_size

日志文件大小。默认5 MB

ClientConfiguration.setMaxLogSize

maxErrorRetry

请求失败后最大的重试次数。默认2次。

ClientConfiguration.setMaxErrorRetry

customCnameExcludeList

列表中的元素将跳过CNAME解析。

ClientConfiguration.setCustomCnameExcludeList

proxyHost

代理服务器主机地址。

ClientConfiguration.setProxyHost

proxyPort

代理服务器端口。

ClientConfiguration.setProxyPort

mUserAgentMark

用户代理中HTTP的User-Agent头。

ClientConfiguration.setUserAgentMark

httpDnsEnable

是否开启httpDns。

  • true:2.9.12以下版本默认开启httpDns。

  • false:2.9.12及以上版本默认关闭httpDns。

ClientConfiguration.setHttpDnsEnable

checkCRC64

是否开启CRC64校验。取值如下:

  • true:开启CRC64校验。

  • false(默认值):关闭CRC64校验。

ClientConfiguration.setCheckCRC64

followRedirectsEnable

是否开启HTTP重定向。取值如下:

  • true:开启HTTP重定向。

  • false(默认值):关闭HTTP重定向。

ClientConfiguration.setFollowRedirectsEnable

okHttpClient

自定义okhttpClient。

ClientConfiguration.setOkHttpClient

以下代码用于使用ClientConfiguration配置OSSClient参数。

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
String endpoint = "yourEndpoint";
// 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 从STS服务获取的安全令牌(SecurityToken)。
String securityToken = "yourSecurityToken";

ClientConfiguration configuration = new ClientConfiguration();
// 设置最大并发数,默认值5。
// configuration.setMaxConcurrentRequest(3);
// 设置Socket层传输数据的超时时间,默认值60s。
// configuration.setSocketTimeout(50000);
// 设置建立连接的超时时间,默认值60s。
// configuration.setConnectionTimeout(50000);
// 设置日志文件大小,默认值5 MB。
// configuration.setMaxLogSize(3 * 1024 * 1024);
// 请求失败后最大的重试次数,默认值2。
// configuration.setMaxErrorRetry(3);
// 列表中的元素将跳过CNAME解析。
// List<String> cnameExcludeList = new ArrayList<>();
// cnameExcludeList.add("cname");
// configuration.setCustomCnameExcludeList(cnameExcludeList);
// 代理服务器主机地址。
// configuration.setProxyHost("yourProxyHost");
// 代理服务器端口。
// configuration.setProxyPort(8080);
// 用户代理中HTTP的User-Agent头。
// configuration.setUserAgentMark("yourUserAgent");
// 是否开启CRC校验,默认值false。
// configuration.setCheckCRC64(true);
// 是否开启HTTP重定向,默认值false。
// configuration.setFollowRedirectsEnable(true);
// 设置自定义OkHttpClient。
// OkHttpClient.Builder builder = new OkHttpClient.Builder();
// configuration.setOkHttpClient(builder.build());

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
// 创建OSSClient实例。
OSSClient oss = new OSSClient(getApplicationContext(),endpoint, credentialProvider, configuration);

启用日志

移动端的使用环境比较复杂。会出现部分区域或某一个时段无法正常使用OSS SDK的情况。为了进一步方便开发者定位问题,OSS SDK在开启日志记录功能后,会将一些日志信息记录在本地。如需开启,需要在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();              
说明

您可以自行选择将文件上传至服务器,或者选择接入阿里云日志服务上传日志文件。

同步接口和异步接口说明

考虑到移动端开发场景下不允许在UI线程执行网络请求的编程规范,Android SDK对上传和下载接口同时提供了同步和异步两种调用示例,其他接口以异步调用示例为主。

  • 同步调用

    • 同步接口调用后会阻塞等待结果返回。

    • 同步接口不能在UI线程调用。

    • 调用同步接口遇到异常时,将直接抛出ClientException或者ServiceException异常。ClientException异常是指本地遇到的异常,如网络异常参数非法等。ServiceException异常是指OSS返回的服务异常,如鉴权失败、服务器错误等。

  • 异步调用

    • 异步接口需要在请求时传入回调函数,请求的执行结果将在回调中处理。

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

    • 调用异步接口时,函数会直接返回一个Task。

      OSSAsyncTask task = oss.asyncGetObejct(...);
      task.cancel(); // 取消任务。
      task.waitUntilFinished(); // 等待直到任务完成。
      GetObjectResult result = task.getResult(); // 阻塞等待结果返回。           
  • 本页导读 (1)