阿里雲團隊努力不懈,力求將最新的技術內容更快地以您最熟悉的語言呈現。本文由簡體中文內容自動轉碼而成,過程無人工干預。阿里雲不保證此自動轉碼的準確性、完整性及時效性。因轉碼造成的任何內容錯誤及因此可能帶來的損失,阿里雲概不負責,敬請見諒。本文内容請以簡體中文版本為準。
全部產品
Search
文件中心

初始化

更新時間: Oct 19, 2018

OSSClient 是 OSS 服務的 Android 用戶端,它為調用者提供了一系列的方法,可以用來操作,管理儲存空間(bucket)和檔案(object)等。在使用 SDK 發起對 OSS 的請求前,您需要初始化一個 OSSClient 執行個體,並對它進行一些必要設定。

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樣本如下:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. String stsServer = "STS應用伺服器位址,例如http://abc.com"
  3. //推薦使用OSSAuthCredentialsProvider。token過期可以及時更新
  4. OSSCredentialProvider credentialProvider = new OSSAuthCredentialsProvider(stsServer);
  5. //該配置類如果不設定,會有預設配置,具體可看該類
  6. ClientConfiguration conf = new ClientConfiguration();
  7. conf.setConnectionTimeout(15 * 1000); // 連接逾時,預設15秒
  8. conf.setSocketTimeout(15 * 1000); // socket逾時,預設15秒
  9. conf.setMaxConcurrentRequest(5); // 最大並發請求數,預設5個
  10. conf.setMaxErrorRetry(2); // 失敗後最大重試次數,預設2次
  11. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

說明:更多鑒權方式,請參考存取控制

設定EndPoint為cname

如果您已經在bucket上綁定cname,將該cname直接設定到endPoint即可。如:

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

啟用日誌

移動端的使用環境比較複雜。會出現部分區域或某一個時段無法正常使用oss sdk的情況。為了進一步方便開發人員定位問題,oss sdk 在開啟日誌記錄功能後,會將一些log資訊記錄在本地。如需開啟需要在OSSClient使用之前進行初始化,調用如下方法即可。

說明:

  • 記錄檔內建sd卡路徑\OSSLog\logs.csv。
  • 您可以自行選擇將檔案上傳至伺服器,進一步追蹤問題。
  • 您還可以接入阿里雲SLSLog Service進行記錄檔上傳,詳情請參考Log Service傳送門
  1. //日誌的樣式
  2. //通過調用OSSLog.enableLog()開啟可以在控制台看到日誌,
  3. //並且會支援寫入手機sd卡中的一份記錄檔位置在內建sd卡路徑\OSSLog\logs.csv 預設不開啟
  4. //日誌會記錄oss操作行為中的請求資料,返回資料,異常資訊
  5. //例如requestId,response header等,下邊是一個日誌記錄case
  6. //android_version:5.1 android版本
  7. //mobile_model:XT1085 android手機型號
  8. //network_state:connected 網路狀況
  9. //network_type:WIFI 網路連接類型
  10. //具體的操作行為資訊:
  11. //[2017-09-05 16:54:52] - Encounter local execpiton: //java.lang.IllegalArgumentException: The bucket name is invalid.
  12. //A bucket name must:
  13. //1) be comprised of lower-case characters, numbers or dash(-);
  14. //2) start with lower case or numbers;
  15. //3) be between 3-63 characters long.
  16. //------>end of log
  17. OSSLog.enableLog(); //調用此方法即可開啟日誌

設定網路參數

也可以在初始化的時候設定詳細的ClientConfiguration:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. // 在移動端建議使用STS的方式初始化OSSClient,更多資訊參考:[存取控制]
  3. OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
  4. ClientConfiguration conf = new ClientConfiguration();
  5. conf.setConnectionTimeout(15 * 1000); // 連接逾時,預設15秒
  6. conf.setSocketTimeout(15 * 1000); // socket逾時,預設15秒
  7. conf.setMaxConcurrentRequest(5); // 最大並發請求書,預設5個
  8. conf.setMaxErrorRetry(2); // 失敗後最大重試次數,預設2次
  9. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);

對 SDK 中同步介面、非同步介面的一些說明

考慮到移動端開發場景下不允許在UI線程執行網路請求的編程規範,SDK大多數介面都提供了同步、非同步兩種調用方式,同步介面調用後會阻塞等待結果返回,而非同步介面需要在請求時傳入回呼函數,請求的執行結果將在回調中處理。

同步介面不能在UI線程調用。遇到異常時,將直接拋出ClientException或者ServiceException異常,前者指本地遇到的異常如網路異常、參數非法等;後者指OSS返回的服務異常,如鑒權失敗、伺服器錯誤等。

非同步請求遇到異常時,異常會在回呼函數中處理。

此外,調用非同步介面時,函數會直接返回一個Task,Task可以取消、等待直到完成、或者直接獲取結果。如:

  1. OSSAsyncTask task = oss.asyncGetObejct(...);
  2. task.cancel(); // 可以取消任務
  3. task.waitUntilFinished(); // 等待直到任務完成
  4. GetObjectResult result = task.getResult(); // 阻塞等待結果返回

介面支援同步和非同步兩種調用方式,考慮到簡潔性,本文檔中只有部分重要介面會同時提供同步、非同步兩種調用的樣本,其他介面暫時以非同步呼叫的樣本為主。

設定是否開啟DNS配置

  1. ClientConfiguration conf = new ClientConfiguration();
  2. conf.setHttpDnsEnable(true);//預設是true 開啟,需要關閉可以設定false

設定自訂user-agent

  1. ClientConfiguration conf = new ClientConfiguration();
  2. //設定的ua會預設添加到sdk預設ua的最後邊,取得時候自行去最後一個即可。
  3. conf.setUserAgentMark("customUserAgent");