OSSClient は、OSS の Android クライアントです。呼び出し元は OSSClient が提供する一連のメソッドを使用して、バケットとオブジェクトを操作したり管理したりできます。OSS Android SDK を使用して OSS へのリクエストを開始する前に、OSSClient インスタンスを初期化し、必要な設定を完了する必要があります。
OSSClientのライフサイクルがアプリケーションのライフサイクルと一致することを確認してください。 アプリケーションの起動時にグローバルOSSClientを作成し、アプリケーションの終了時にグローバルOSSClientを破棄します。
エンドポイントの決定
エンドポイントは、リージョン内の Alibaba Cloud OSS のアドレスです。次の 2 つの形式が利用できます。
エンドポイントタイプ | 説明 |
---|---|
OSS リージョンアドレス | OSS バケットが存在するリージョンのアドレス。さまざまなリージョンのエンドポイントの詳細については、「OSS アクセスドメイン名」を参照してください。 |
ユーザー定義ドメイン名 | OSS ドメインを指定する CNAME を含む、ユーザー定義のドメイン名。 |
エンドポイントの詳細については、OSS アクセスドメイン名を参照してください。
OSS リージョンアドレス
次の 2 つの方法のいずれかを使用して、OSS バケットが存在するリージョンのアドレスにマッピングされたエンドポイントを検索できます。
- エンドポイントとリージョンの間のマッピング関係を照会できます。詳細については、OSS アクセスドメイン名。
- Alibaba Cloud OSS コンソールにログオンして [Bucket Overview] ページを開き、バケットドメインのサフィックスを見つけます。たとえば、バケットドメイン
bucket-1.oss-cn-hangzhou.aliyuncs.com
のサフィックスoss-cn-hangzhou.aliyuncs.com
がインターネット上のバケットのエンドポイントです。
CNAME
CNAME を使用してドメインをバケットにバインドし、ドメインを使用してバケット内のオブジェクトにアクセスできます。
たとえば、new-image.xxxxx.com ドメインを深圳の “image” という名前のバケットにバインドする必要がある場合、以下を実行します。
xxxxx.com のドメインホスティングプロバイダーに問い合わせ、
http://new-image.xxxxx.com
をhttp://image.oss-cn-shenzhen.aliyuncs.com
に解決するために使用する新しいドメイン名解決レコードを設定します。レコードタイプは CNAME です。
エンドポイントと資格情報の設定
移動端末は信頼できる環境ではない。AccessKeyID とAccessKeySecretをモバイル端末に保管して、署名要求を行う場合、非常に高いリスクがあります。STS認証モード または 自己署名モードを使用することをお勧めします。詳細については、 アクセス制御 および Application serverを参照してください。EndPointとCredentialProviderの設定の例は次のとおりです。
STS認証モードを使用している場合は、OSSAuthCredentialsProviderを使用してアプリケーションサーバーにアクセスすることをお勧めします。 期限切れのトークンは自動的に更新されます。
詳細については、こちら。
EndPointとCredentialProviderの設定の例を次に示します。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
String stsServer = "http://abc.com is an example of an STS application server address."
//We recommend you use OSSAuthCredentialsProvider because expired tokens can be updated quickly.
OSSCredentialProvider credentialProvider = new OSSAuthCredentialsProvider(stsServer);
//If this configuration class is not set, default configuration applies. For more information, see description of the class.
ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // Connection time-out. The default value is 15 seconds.
conf.setSocketTimeout(15 * 1000); // Socket time-out. The default value is 15 seconds.
conf.setMaxConcurrentTaskNum(5); // The maximum number of concurrent requests. The default value is 5.
conf.setMaxErrorRetry(2); // The maximum number of retries after a failure. The default value is 2.
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
注意: 認証モードの詳細については、「アクセス制御」を参照してください。
CNAME に従ったエンドポイントの設定
CNAME をバケットにバインドした場合、CNAME と同じエンドポイントを設定できます。次に例を示します。
String endpoint = "http://new-image.xxxxx.com";
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
注意:認証モードの詳細については、「アクセス制御」を参照してください。
ログを有効にする
モバイル端末は、使用中に複雑な環境を有する。 OSS SDKは、地域内または一定期間内に機能しないことがあります。 開発者が問題を見つけるのを助けるために、OSS SDKは、ログ機能が有効になった後、いくつかのログをローカルディレクトリに記録します。 ログ機能を有効にするには、OSSクライアントを使用する前に、次のメソッドを呼び出してOSSクライアントを初期化する必要があります。
補足説明:
- ログファイルは、\ OSSLog \ logs.csvのSDカードに保存されます。
- ファイルをサーバーにアップロードして、問題をさらに追跡することができます。
- Alibaba Cloud Log Serviceに接続後、ログファイルをアップロードすることもできます。 ログサービスに移動
//The log style.
//You can call the OSSLog.enableLog() method to enable displaying logs in the console.
//This setting also supports saving one copy of the log file to the SD card of the mobile phone at \OSSLog\logs.csv. This setting is not enabled by default.
//The log records the request data, returned data and exceptions of OSS operations.
//Such as requestId and response header. The following is a log record case.
//android_version: 5.1. The Android version
//mobile_model: XT1085 . The Android phone model
//network_state: connected. The network status
//network_type: WIFI. The network connection type
//Specific operation information:
//[2017-09-05 16:54:52] - Encounter local exception: //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(); //Call this method to enable logs.
ネットワークパラメーターの設定
次のように、初期化プロセス中に ClientConfiguration の詳細を設定できます。
String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
// // We recommend that you initialize OSSClient using STS on the mobile terminal. For more details, refer to "Access Control"
OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
ClientConfiguration conf = new ClientConfiguration();
conf.setConnectionTimeout(15 * 1000); // Connection timeout. The default value is 15 seconds.
conf.setSocketTimeout(15 * 1000); // Socket timeout. The default value is 15 seconds.
conf.setMaxConcurrentRequest(5); // The maximum number of concurrent requests. The default value is 5.
conf.setMaxErrorRetry(2); // The maximum number of retries after a failed request. The default value is 2.
OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);
SDKの同期インタフェースと非同期インタフェース
ネットワーク要求はモバイル開発のUIスレッドで処理できないため、ほとんどのSDKインターフェイスでは、要求を処理するための同期呼び出しと非同期呼び出しがサポートされています。呼び出された後、同期インターフェイスは返された結果を待つ間に他の要求をブロックします。非同期インターフェイスは、要求の結果を処理するコールバック関数をインポートする必要があります。
UIスレッドで同期インタフェースを呼び出すことはできません。 ClientExceptionまたはServiceExceptionが発生すると、すぐにスローされます。 ClientExceptionは、ネットワーク例外、無効なパラメータなど、ローカル例外を指します。 ServiceExceptionは、認証失敗やサーバーエラーなど、OSSが返すサービス例外を指します。
非同期要求が処理されている間に例外が発生した場合、それはコールバック関数によって処理されます。
非同期インターフェイスが呼び出されると、この関数はタスクを返します。タスクを取り消したり、タスクが完了するのを待ったり、結果を直接取得したりすることができます。例えば:
OSSAsyncTask task = oss.asyncGetObejct(...);
task.cancel(); // Cancel the task
task.waitUntilFinished(); // Wait until the task is finished
GetObjectResult result = task.getResult(); // Block other requests and wait for the returned results
インタフェースは、同期メソッドと非同期メソッドの両方をサポートしています。 簡単にするために、このドキュメントでは、同期モードと非同期モードで重要なインターフェイスを呼び出す方法の例を示します。 他のインタフェースでは、非同期呼び出しの例のみが提供されます。
DNS設定を有効にするかどうかを設定する
ClientConfiguration conf = new ClientConfiguration();
conf.setHttpDnsEnable(true);//The default value is "true", meaning enable. To disable the feature, set the value to "false".
カスタムユーザーエージェントを設定する
ClientConfiguration conf = new ClientConfiguration();
//The set ua is added to the end of the default ua of the SDK by default. Use the last ua value.
conf.setUserAgentMark("customUserAgent");