The TOS SDK provides a set of interfaces for interacting with TOS services, enabling the management of resources such as buckets and objects. You can initialize TOSV2Client using methods such as AccessKey/SecretKey, STS (Security Token Service), and others. TOS also supports configuring optional parameters such as connection establishment timeout and maximum number of idle connections. You may configure settings in accordance with your business requirements by referring to this document.

Creating a TosClient

Create using STS parameters (specify SecurityToken; recommended)

Android mobile devices constitute an untrusted environment; storing the accessKey and secretKey directly on the device for request signing carries a high risk. It is strongly recommended to use STS parameters when creating TOSV2Client.

STS (Security Token Service) is a service that grants temporary access to third-party users. With STS, you can provide token access credentials with customizable expiration times to third-party applications or sub-users.

TOS supports temporary authorized access via STS, and the Android SDK provides corresponding access interfaces. Configure the authorized token in the SDK to enable access to the TOS service.

The following code demonstrates how to initialize TOSV2Client using STS.

Create using required parameters (Region + Endpoint + AccessKey/SecretKey, not recommended)

For information on the Regions and Endpoints supported by TOS, please refer to Regions and Endpoints.

AKSK information can be obtained from environment variables. You may refer to the following steps to configure AKSK information in environment variables.

macOS

Linux

Windows

Open the terminal and execute the following command to open the file.

Add AKSK information at the end of the document.

Save the file and exit.

Execute the following command to make the configuration information take effect.

Execute the following command to verify the configuration information.

If the configuration is successful, the following example will be returned:

The following is sample code for initializing TOSV2Client.

Common Configuration Scenarios

Configure Timeout Mechanism

The Android SDK provides the following timeout parameters for configuring HTTP request timeouts.

readTimeoutMills: HTTP read request timeout period, measured in milliseconds. The default value is 30000, which corresponds to 30 seconds.

writeTimeoutMills: Specifies the HTTP write request timeout in milliseconds. The default value is 30000 (30 seconds).

connectTimeoutMills: The timeout period for establishing an HTTP connection, measured in milliseconds. The default value is 10000, which corresponds to 10 seconds.

The following code demonstrates how to configure the aforementioned timeout parameters.

Configuring Retry Strategies

Beginning with version 2.2.0, a retry mechanism was added to the underlying layer of the Android SDK. When a client request times out, or the server returns a 5xx error or a 429 error, the SDK will perform backoff and retry for requests to interfaces that support idempotent semantics.

Retry Scenarios

The following interfaces will retry when a client request times out, or when the server returns a 5xx error or a 429 error.

All GET/HEAD-type interfaces, such as GetObject, HeadObject, and HeadBucket.

Some interfaces are of the PUT/DELETE type, such as PutObjectACL and DeleteObject.

For the PutObject/UploadPart interfaces, if the uploaded content (of InputStream type) supports markSupported(), the operation can be considered to have idempotent semantics. For example, content may be a string, a local file, a memory array, a ByteArrayInputStream, etc.

PutObjectFromFile, UploadPartFromFile, and SetObjectMeta interfaces.

Except for AppendObject, all POST-type HTTP interfaces will only retry when the server returns a 5xx error or a 429 error; retries will not be attempted in the event of a client timeout.

Retry Strategy

The Android SDK performs exponential backoff retries according to the configured number of attempts, with the default set to three attempts.

Sample Code

The following code demonstrates how to configure the retry count for the SDK.

To disable the retry strategy, set maxRetryCount in the above code to a value less than 0, such as maxRetryCount = -1.

Configuration Data Validation

The TOS Android SDK supports verifying the integrity of uploaded and downloaded data through CRC calculation. For upload interfaces, including PutObject, AppendObject, UploadPart, PutObjectFromFile, and UploadFile, the server returns the Crc64 value of the uploaded data upon completion of the request. The SDK compares this value with the locally computed Crc64 value, and if they do not match, a TosClientException is thrown.

For the GetObject, GetObjectToFile, and DownloadFile interfaces, the Crc64 value is calculated during the download process. After the download is complete, the SDK compares the CRC64 value returned by the server with the CRC64 value calculated locally. If the values do not match, a TosClientException is thrown.

By default, CRC verification is enabled in the Android SDK. The following code demonstrates how to enable or disable CRC verification.

Configure DNS Cache

In public network environments, TOS service domain names may experience delays in domain name resolution or be unable to resolve for a period of time. To address this, the Android SDK implements a DNS caching mechanism that stores the IP addresses resolved from domain names within the SDK, eliminating the need to perform domain name resolution for every request.

The DNS caching mechanism of the SDK is disabled by default. The following code demonstrates how to configure the DNS cache duration. The default unit is minutes.

Configure Proxy Server

Beginning with version 2.3.0, the Android SDK supports configuring access to proxy servers; currently, only HTTP protocol proxies are supported.

The following code demonstrates how to configure a proxy server.

Configure Connection Pool

The Android SDK provides the following parameters for configuring the underlying HTTP connection pool.

idleConnectionTimeMills: Specifies the maximum idle time for a connection in the HTTP connection pool. If this threshold is exceeded, the connection will be closed. The unit is milliseconds. The default value is 60000 (60 seconds).

maxConnections: Specifies the maximum number of connections in the HTTP connection pool; the default value is 1024.

The following code demonstrates how to configure the above parameters.

Initialization Parameter List

Parameters	Description	Parameter Type	Default Value	Sample Value
accessKey	Access Key ID (密钥ID).	String	null	AKTPYmI1Z****
secretKey	SecretAccess Key: a private access key.	String	null	T1dJM01UU****==
endpoint	Access the domain name.	String	null	tos-cn-beijing.volces.com
region	The region where the TOS server is located.	String	null	cn-beijing
securityToken	The security token in the temporary access credential.	String	null	STSeyJBY2NvdW50SW************
writeTimeoutMills	HTTP write request timeout duration, in milliseconds.	int	30000	30000
connectTimeoutMills	Timeout period for establishing a connection, in milliseconds.	int	10000	10000
idleConnectionTimeMills	If the idle time of an HTTP connection in the connection pool exceeds the value specified by this parameter, the HTTP connection will be closed. Unit: milliseconds.	int	60000	60000
maxConnections	Maximum number of connections in the HTTP connection pool.	int	1024	1024
maxRetryCount	The maximum number of retry attempts after a request failure.	int	3	3
dnsCacheTimeMinutes	DNS cache validity period, in minutes; a value less than or equal to 0 indicates that DNS caching is disabled.	int	0	0
proxyHost	Host address of the proxy server; currently, only the HTTP protocol is supported.	String	null	"localhost"
proxyPort	Proxy server port number.	int	0	8080
proxyUserName	Username for connecting to the proxy server.	String	null	"Alice"
proxyPassword	The password used to connect to the proxy server.	String	null	"pwd123"
enableVerifySSL	Whether to enable SSL certificate verification.	boolean	true	true
enableCrc	Enable CRC verification?	boolean	true	true
clientAutoRecognizeContentType	Enable Content-Type recognition based on object name suffix?	boolean	true	true

Torch Object Storage