Initialization

Last Updated: Dec 21, 2017

The OSSClient is the Android client of OSS. It provides the caller with a series of methods to operate and manage the buckets and objects. Before you use the OSS Android SDK to initiate a request to OSS, you must first initialize an OSSClient instance and complete necessary settings.

Determine an endpoint

An endpoint is the address of Alibaba Cloud OSS in a region. It supports the following two formats:

Endpoint type Description
OSS region address Address of the region where an OSS bucket is located. For more information about the endpoints in various regions, see here.
User-defined domain name Domain name defined by the user, with the CNAME directing to the OSS domain

For more information about endpoints, click to view details.

OSS region address

You can use one of the following two methods to search for an endpoint mapped to the address of the region where an OSS bucket is located:

  • You can query the mapping relationship between the endpoint and the region. For more information, click to view details.
  • You can log on to Alibaba Cloud OSS Console, open the Bucket Overview page, and find the suffix of the bucket domain. For example, the suffix oss-cn-hangzhou.aliyuncs.com of the bucket domain bucket-1.oss-cn-hangzhou.aliyuncs.com is the endpoint of the bucket on the Internet.

CNAME

You can bind your domain to a bucket through the CNAME and access the objects in the bucket through the domain.

For example, you want to bind the domain new-image.xxxxx.com to a bucket named “image” in the Shenzhen region: you must contact your domain hosting provider for xxxxx.com to configure a new domain name resolution record used to resolve http://new-image.xxxxx.com to http://image.oss-cn-shenzhen.aliyuncs.com. The record type is CNAME.

Configure the endpoint and credential

A mobile client is an untrusted environment. An extremely high risk occurs if you store the AccessKeyId and AccessKeySecret in a mobile client for signing requests. We recommend you use STS Authentication Mode or Self-signed Mode. For more information, see Resource Access Management and Direct Transfer on a Mobile client.

To use STS authentication, read the Resource Access Management section to learn RAM basics. The following description is on the premise that you have activated the RAM service and understood RAM-related content. Learn how to retrieve the AccessKeyId and SecretKeyId of the sub-accounts and the RoleArn information.

Improve the AccessKeyId and SecretKeyId in the Script File and the RoleArn parameter information. You can start a local HTTP service using Python. Visit the local service in the client code to get the StsToken.AccessKeyId, StsToken.SecretKeyId and the StsToken.SecurityToken.

For more information, see the STS instructions in the sample Click to view more.

An example of EndPoint and CredentialProvider settings is shown as follows:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. // AccessKeySecret setting in plain text mode is recommended for test purposes only. For more authentication modes, see the "Resource Access Management" section.
  3. // You can also see the STS instructions in the sample to learn more. (https://github.com/aliyun/aliyun-oss-android-sdk/tree/master/app/src/main/java/com/alibaba/sdk/android/oss/app)
  4. OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
  5. //If this configuration class is not set, default configuration applies. For more information, see description of the class.
  6. ClientConfiguration conf = new ClientConfiguration();
  7. conf.setConnectionTimeout(15 * 1000); // Connection time-out. The default value is 15 seconds.
  8. conf.setSocketTimeout(15 * 1000); // Socket time-out. The default value is 15 seconds.
  9. conf.setMaxConcurrentTaskNum(5); // The maximum number of concurrent requests. The default value is 5.
  10. conf.setMaxErrorRetry(2); // The maximum number of retries after a failure. The default value is 2.
  11. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);

Note: For more authentication modes, see Resource Access Management.

Configure the endpoint according to the CNAME

If you have bound the CNAME to the bucket, you can direct the endpoint to the CNAME directly. For example,

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

For more authentication modes, see Resource Access Management.

Enable logs

Mobile terminals have complicated environments during usage. The OSS SDK may fail to function in a region or during a period of time. To help developers locate issues, the OSS SDK records some logs to a local directory after the log feature is enabled. To enable the log feature, you must initialize the OSSClient before using it, by calling the following method.

Supplemental instructions:

  • Log files are stored on the SD card at \OSSLog\logs.csv.
  • You can upload the file to the server to further trace the issue.
  • You can also upload the log files after connecting to Alibaba Cloud Log Service. Go to Log Service.
  1. //The log style.
  2. //You can call the OSSLog.enableLog() method to enable displaying logs in the console.
  3. //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.
  4. //The log records the request data, returned data and exceptions of OSS operations.
  5. //Such as requestId and response header. The following is a log record case.
  6. //android_version: 5.1. The Android version
  7. //mobile_model: XT1085 . The Android phone model
  8. //network_state: connected. The network status
  9. //network_type: WIFI. The network connection type
  10. //Specific operation information:
  11. //[2017-09-05 16:54:52] - Encounter local exception: //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(); //Call this method to enable logs.

Set network parameters

You can set detailed ClientConfiguration during the initialization process as follows:

  1. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  2. // We recommend you initialize OSSClient using STS on the mobile client. For more information, see: [Resource Access Management].
  3. OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider("<StsToken.AccessKeyId>", "<StsToken.SecretKeyId>", "<StsToken.SecurityToken>");
  4. ClientConfiguration conf = new ClientConfiguration();
  5. conf.setConnectionTimeout(15 * 1000); // Connection time-out. The default value is 15 seconds.
  6. conf.setSocketTimeout(15 * 1000); // Socket time-out. The default value is 15 seconds.
  7. conf.setMaxConcurrentTaskNum(5); // The maximum number of concurrent requests. The default value is 5.
  8. conf.setMaxErrorRetry(2); // The maximum number of retries after a failure. The default value is 2.
  9. OSS oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider, conf);

Set whether to enable the DNS settings

  1. ClientConfiguration conf = new ClientConfiguration();
  2. conf.setHttpDnsEnable(true);//The default value is "true", meaning enable. To turn the feature off, set the value to "false".

Set the custom user-agent

  1. ClientConfiguration conf = new ClientConfiguration();
  2. //The set ua is added to the end of the default ua of the SDK by default. Use the last ua value.
  3. conf.setUserAgentMark("customUserAgent");
Thank you! We've received your feedback.