OSSClient是OSS服務的Android用戶端，為調用者提供了一系列的方法進行操作、管理儲存空間（Bucket）和檔案（Object）等。在使用SDK發起對OSS的請求前，您需要初始化一個OSSClient執行個體，並對OSSClient執行個體進行必要的設定。
OSSClient的生命週期需與應用程式的生命週期保持一致。即您需要在應用啟動時建立一個全域的OSSClient，在應用結束時銷毀OSSClient。
初始化OSSClient
移動終端是一個不受信任的環境，把AccessKeyId和AccessKeySecret直接儲存在終端用來加簽請求，存在極高的風險。推薦使用STS鑒權模式或自簽名模式。
您可以通過以下多種方式建立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";
// yourEndpoint填寫Bucket所在地區。以華東1（杭州）為例，region填寫為cn-hangzhou。
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);
// 建立OSSClient執行個體。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);使用自訂網域名建立OSSClient
以下代碼用於使用自訂網域名建立OSSClient。
// yourEndpoint填寫自訂網域名。
String endpoint = "yourEndpoint";
// 從STS服務擷取的臨時存取金鑰（AccessKey ID和AccessKey Secret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 從STS服務擷取的安全性權杖（SecurityToken）。
String securityToken = "yourSecurityToken";
// yourEndpoint填寫Bucket所在地區。以華東1（杭州）為例，region填寫為cn-hangzhou。
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);
// 建立OSSClient執行個體。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);專有雲或專有域環境建立OSSClient
以下代碼用於在專有雲或專有域環境建立OSSClient。
// yourEndpoint填寫Bucket所在地區對應的Endpoint。
String endpoint = "yourEndpoint";
// 從STS服務擷取的臨時存取金鑰（AccessKey ID和AccessKey Secret）。
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// 從STS服務擷取的安全性權杖（SecurityToken）。
String securityToken = "yourSecurityToken";
// yourEndpoint填寫Bucket所在地區。以華東1（杭州）為例，region填寫為cn-hangzhou。
String region = "yourRegion";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
ClientConfiguration configuration = new ClientConfiguration();
// 跳過CNAME解析。
List<String> excludeList = new ArrayList<>();
excludeList.add(endpoint);
configuration.setCustomCnameExcludeList(excludeList);
// 建立OSSClient執行個體。
configuration.setSignVersion(SignVersion.V4);
// 建立OSSClient執行個體。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);配置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 | Proxy 伺服器主機地址。 | ClientConfiguration.setProxyHost |
proxyPort | Proxy 伺服器連接埠。 | ClientConfiguration.setProxyPort |
mUserAgentMark | 使用者代理程式中HTTP的User-Agent頭。 | ClientConfiguration.setUserAgentMark |
httpDnsEnable | 是否開啟httpDns。
| ClientConfiguration.setHttpDnsEnable |
checkCRC64 | 是否開啟CRC64校正。取值如下：
| ClientConfiguration.setCheckCRC64 |
followRedirectsEnable | 是否開啟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";
// yourEndpoint填寫Bucket所在地區。以華東1（杭州）為例，region填寫為cn-hangzhou。
String region = "yourRegion";
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);
// Proxy 伺服器主機地址。
// configuration.setProxyHost("yourProxyHost");
// Proxy 伺服器連接埠。
// 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);
configuration.setSignVersion(SignVersion.V4);
// 建立OSSClient執行個體。
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);啟用日誌
移動端的使用環境比較複雜。會出現部分地區或某一個時段無法正常使用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(); 您可以自行選擇將檔案上傳至伺服器，或者選擇接入阿里雲Log Service上傳記錄檔。
同步介面和非同步介面說明
考慮到移動端開發情境下不允許在UI線程執行網路請求的編程規範，Android SDK對上傳和下載介面同時提供了同步和非同步兩種調用樣本，其他介面以非同步呼叫樣本為主。
同步調用
同步介面調用後會阻塞等待結果返回。
同步介面不能在UI線程調用。
調用同步介面遇到異常時，將直接拋出ClientException或者ServiceException異常。ClientException異常是指本地遇到的異常，如網路異常參數非法等。ServiceException異常是指OSS返回的服務異常，如鑒權失敗、伺服器錯誤等。
非同步呼叫
非同步介面需要在請求時傳入回呼函數，請求的執行結果將在回調中處理。
非同步請求遇到異常時，異常會在回呼函數中處理。
調用非同步介面時，函數會直接返回一個Task。
OSSAsyncTask task = oss.asyncGetObejct(...); task.cancel(); // 取消任務。 task.waitUntilFinished(); // 等待直到任務完成。 GetObjectResult result = task.getResult(); // 阻塞等待結果返回。