Object Storage Service:Initialization (Android SDK)

Initialize OSSClient

OSSClient requires a credential provider (OSSCredentialProvider) that handles authentication. This decouples credential management from the client, so you can rotate or refresh credentials without re-creating the client.

Choose the initialization method that matches your environment:

• STS (recommended) — for most production apps

• Custom domain name — when accessing OSS through a custom endpoint

• Apsara Stack or private domain — when canonical name (CNAME) resolution must be skipped

For upload and download examples, see Quick Start (Android SDK). The OSSClient initialization method for listing buckets differs from the examples below. See List buckets (Android SDK).

// Replace <your-endpoint> with the endpoint for the region where your bucket is located.
// Example: https://oss-cn-hangzhou.aliyuncs.com
String endpoint = "<your-endpoint>";

// Temporary credentials obtained from STS
String accessKeyId = "<your-sts-access-key-id>";
String accessKeySecret = "<your-sts-access-key-secret>";
String securityToken = "<your-sts-security-token>";

// Replace <your-region> with the region ID. Example: cn-hangzhou
String region = "<your-region>";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);

ClientConfiguration config = new ClientConfiguration();
// Set the request signing version to Signature Version 4 (V4).
config.setSignVersion(SignVersion.V4);

OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);

// Replace <your-custom-domain> with your custom domain name.
String endpoint = "<your-custom-domain>";

// Temporary credentials obtained from STS
String accessKeyId = "<your-sts-access-key-id>";
String accessKeySecret = "<your-sts-access-key-secret>";
String securityToken = "<your-sts-security-token>";

// Replace <your-region> with the region ID. Example: cn-hangzhou
String region = "<your-region>";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);

ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);

OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);

// Replace <your-endpoint> with the endpoint provided by your Apsara Stack or private domain environment.
String endpoint = "<your-endpoint>";

// Temporary credentials obtained from STS
String accessKeyId = "<your-sts-access-key-id>";
String accessKeySecret = "<your-sts-access-key-secret>";
String securityToken = "<your-sts-security-token>";

// Replace <your-region> with the region ID. Example: cn-hangzhou
String region = "<your-region>";

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);

ClientConfiguration configuration = new ClientConfiguration();
// Skip CNAME resolution for this endpoint.
List<String> excludeList = new ArrayList<>();
excludeList.add(endpoint);
configuration.setCustomCnameExcludeList(excludeList);
configuration.setSignVersion(SignVersion.V4);

OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);

Configure OSSClient

ClientConfiguration lets you tune connection behavior, retries, logging, and more. All parameters are optional — the defaults work for most apps.

The following example shows how to apply a custom ClientConfiguration. Uncomment and adjust any settings you need.

String endpoint = "<your-endpoint>";
String accessKeyId = "<your-sts-access-key-id>";
String accessKeySecret = "<your-sts-access-key-secret>";
String securityToken = "<your-sts-security-token>";
String region = "<your-region>";

ClientConfiguration configuration = new ClientConfiguration();

// Maximum concurrent requests. Default: 5.
// configuration.setMaxConcurrentRequest(3);

// Socket-layer data transmission timeout in milliseconds. Default: 60000.
// configuration.setSocketTimeout(50000);

// Connection establishment timeout in milliseconds. Default: 60000.
// configuration.setConnectionTimeout(50000);

// Maximum log file size. Default: 5 MB.
// configuration.setMaxLogSize(3 * 1024 * 1024);

// Maximum retries after a request fails. Default: 2.
// configuration.setMaxErrorRetry(3);

// Skip CNAME resolution for specified endpoints.
// List<String> cnameExcludeList = new ArrayList<>();
// cnameExcludeList.add("cname");
// configuration.setCustomCnameExcludeList(cnameExcludeList);

// Proxy server settings.
// configuration.setProxyHost("<your-proxy-host>");
// configuration.setProxyPort(8080);

// Custom string appended to the User-Agent header.
// configuration.setUserAgentMark("<your-user-agent>");

// Enable CRC-64 verification. Default: false.
// configuration.setCheckCRC64(true);

// Follow HTTP redirects. Default: false.
// configuration.setFollowRedirectsEnable(true);

// Custom OkHttpClient.
// OkHttpClient.Builder builder = new OkHttpClient.Builder();
// configuration.setOkHttpClient(builder.build());

configuration.setSignVersion(SignVersion.V4);

OSSCredentialProvider credentialProvider = new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);
OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);

Enable logging

The mobile environment is complex and issues can be difficult to reproduce. Enable logging before using OSSClient to capture request data, response data, and exception details locally.

Call OSSLog.enableLog() before initializing OSSClient:

// Enable logging. Logs are viewable in the console.
// Log files are also written to \OSSLog\logs.csv on the device's built-in SD card (disabled by default).
OSSLog.enableLog();

Each log entry captures:

• Android version and device model

• Network state and connection type

• Request and response details (request ID, response headers)

• Exception information

Sample log entry:

android_version: 5.1
mobile_model: XT1085
network_state: connected
network_type: WIFI
[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

To store logs off-device, upload the log files to your own server or use Alibaba Cloud Simple Log Service.

Synchronous and asynchronous interfaces

The Android SDK provides both synchronous and asynchronous interfaces. Because Android prohibits network calls on the UI thread, use asynchronous interfaces for all network operations in production code.

Synchronous interfaces

A synchronous call blocks the calling thread until the operation completes. Never call synchronous interfaces on the UI thread.

When an error occurs, the SDK throws one of the following exceptions:

• ClientException — a local error, such as a network connectivity issue or an invalid parameter

• ServiceException — an error returned by OSS, such as an authentication failure or a server error

Asynchronous interfaces

An asynchronous call returns an OSSAsyncTask immediately. Pass a callback to handle the result or any exceptions.

OSSAsyncTask task = oss.asyncGetObject(...);
task.cancel();             // Cancel the task
task.waitUntilFinished();  // Block until the task completes
GetObjectResult result = task.getResult(); // Block and get the result

For upload and download interfaces, both synchronous and asynchronous examples are provided. For all other interfaces, asynchronous examples are the primary examples.

What's next

• Quick Start (Android SDK) — upload and download examples

• List buckets (Android SDK) — bucket listing with a different initialization method