Initialization - Tablestore - Alibaba Cloud Documentation Center

OTSClient is a client for Tablestore that provides various methods for you to manage tables and perform read and write operations on a single row or multiple rows. Before you can use Tablestore SDK for Java to send a request, you need to initialize an OTSClient instance and modify its default ClientConfiguration. Before you can use the TimeSeries model, you need to initialize the TimeseriesClient.

Obtain an endpoint

An endpoint is a domain name that is used to access a Tablestore instance in a region. The following table describes the examples of endpoints in the supported formats.

Example	Description
http://sun.cn-hangzhou.ots.aliyuncs.com	A public endpoint that is used to access the sun instance in the China (Hangzhou) region over HTTP.
https://sun.cn-hangzhou.ots.aliyuncs.com	A public endpoint that is used to access the sun instance in the China (Hangzhou) region over HTTPS.

Important

You can connect to Tablestore by using either public or private endpoints. For more information, see Endpoints.

To query the endpoints of your Tablestore instance, perform the following steps:

Log on to the Tablestore console.
On the Overview page, click the name of the desired instance.
In the Instance Access Address section of the Instance Details tab, view the endpoint of the instance.

Configure an AccessKey pair

Before connecting to Tablestore, you need a valid AccessKey pair to verify your identity. Tablestore supports the following types of AccessKey pairs:

Important

To prevent security risks caused by the leakage of the AccessKey pair of your Alibaba Cloud account, we recommend that you create a RAM user that is granted the permissions to access Tablestore and use the AccessKey pair of the RAM user to access Tablestore.

The AccessKey pair of an Alibaba Cloud account. To obtain the AccessKey pair of an Alibaba Cloud account, perform the following steps:
1. On the Alibaba Cloud official website, sign in to Alibaba Cloud.
2. Create an AccessKey pair that consists of an AccessKey ID and an AccessKey secret. For more information, see Obtain an AccessKey pair.
The AccessKey pair of a RAM user that is authorized to access Tablestore. To obtain the AccessKey pair of a RAM user, perform the following steps:
1. Log on to the RAM console by using an Alibaba Cloud account. Then, create a RAM user or find an existing RAM user.
2. Grant the RAM user the permissions to access Tablestore.
3. After the RAM user is granted the permissions to access Tablestore, you can use the AccessKey pair of the RAM user to access Tablestore.
Temporary access credentials that are obtained from Security Token Service (STS). The following process shows how to obtain temporary access credentials from STS:
1. The application server uses RAM or STS to obtain temporary access credentials and send them to you. The access credentials consist of a temporary AccessKey ID, a temporary AccessKey secret, and a security token.
2. You can use the access credentials to access Tablestore.

Configure environment variables

Configure environment variables based on your operating system.

The OTS_AK_ENV environment variable indicates the AccessKey ID of an Alibaba Cloud account or a RAM user. The OTS_SK_ENV environment variable indicates the AccessKey secret of an Alibaba Cloud account or a RAM user. Specify the AccessKey pair based on your requirements.

Configure environment variables in Linux and macOS
Run the following command to configure environment variables. Replace<access_key_id> with your actual AccessKey ID and <access_key_secret> with your actual AccessKey secret.
```
export OTS_AK_ENV=<access_key_id>
export OTS_SK_ENV=<access_key_secret>
```
Configure environment variables in Windows
Create an environment variable file and add the OTS_AK_ENV and OTS_SK_ENV environment variables to the file. Then, set the OTS_AK_ENV environment variable to the AccessKey ID and the OTS_SK_ENV environment variable to the AccessKey Secret. Then, restart Windows for the configuration to take effect.

Initialize a client

If you want to use the Tablestore SDK, create a client and call the operations in the client to access Tablestore. The operations in the client provide the same functions as the RestfulAPIs provided by Tablestore.

The Tablestore SDK provides SyncClient for synchronous operations and AsyncClient for asynchronous operations. After you call a synchronous operation, it is immediately executed. You can call synchronous operations to obtain information about various features of Tablestore. Compared with synchronous operations, asynchronous operations are more flexible. Multithreading provides higher performance than asynchronous operations. You can choose asynchronous operations or multithreading based on your business requirements.

Note

SyncClient and AsyncClient are thread-safe. You can use the clients to manage internal threads and connection resources. We recommend that you create a global client. This way, you do not need to create a client for each thread or request.

After you obtain the AccessKey ID and AccessKey secret, you can perform the following steps to initialize a client:

Important

The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey Secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources that belong to your account may be compromised. In this example, the AccessKey pair is specified in the environment variables, thus identifies verification.

Use default configurations to create a SyncClient

final String endPoint = ""; 
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
final String instanceName = "";
SyncClient client = new SyncClient(endPoint, accessKeyId, accessKeySecret, instanceName);

The following table describes the parameters.

Parameter	Example	Overview
endPoint	https://myinstance.cn-hangzhou.ots.aliyuncs.com	The endpoint of the instance. For more information, see Obtain an endpoint.
accessKeyId	System.getenv("OTS_AK_ENV")	The AccessKey pair that is specified in environment variables. Make sure that the environment variables are configured. For more information, see Configure environment variables.
accessKeySecret	System.getenv("OTS_SK_ENV")
instanceName	myinstance	The name of the instance. For more information, see Instance.

Use custom configurations to create a SyncClient

// ClientConfiguration provides multiple configuration items. Only the most commonly used items are listed. 
ClientConfiguration clientConfiguration = new ClientConfiguration();
// Specify a time-out period for establishing connection. Unit: milliseconds. 
clientConfiguration.setConnectionTimeoutInMillisecond(5000);
// Specify a time-out period for the socket connection. Unit: milliseconds. 
clientConfiguration.setSocketTimeoutInMillisecond(5000);
// Configure a retry policy. If you do not configure a retry policy, the default retry policy is used. 
clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
SyncClient client = new SyncClient(endPoint, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

Initialize the TimeseriesClient

If you want to use the time series model, you need to initialize the TimeseriesClient. This is because the time series model needs a separate client.

The Tablestore SDK provides TimeseriesClient for synchronous operations and AsyncTimeseriesClient for asynchronous operations.

After you obtain AccessKey ID and AccessKey secret, you can perform the following steps to initialize the TimeseriesClient:

Use default configurations to create a TimeseriesClient

final String endPoint = "";
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
final String instanceName = "";
TimeseriesClient client = new TimeseriesClient(endPoint, accessKeyId, accessKeySecret, instanceName);

The following table describes the parameters.

Parameter	Example	Overview
endPoint	https://myinstance.cn-hangzhou.ots.aliyuncs.com	The endpoint of the instance. For more information, see Obtain an endpoint.
accessKeyId	System.getenv("OTS_AK_ENV")	The AccessKey pair that is specified in environment variables. Make sure that the environment variables are configured. For more information, see Configure environment variables.
accessKeySecret	System.getenv("OTS_SK_ENV")
instanceName	myinstance	The name of the instance. For more information, see Instance.

Use custom configurations to create a TimeseriesClient

// ClientConfiguration provides multiple configuration items. Only the most commonly used items are listed. 
ClientConfiguration clientConfiguration = new ClientConfiguration();
// Specify a time-out period for establishing connection. Unit: milliseconds. 
clientConfiguration.setConnectionTimeoutInMillisecond(5000);
// Specify a time-out period for the socket connection. Unit: milliseconds. 
 clientConfiguration.setSocketTimeoutInMillisecond(5000);
// Configure a retry policy. If you do not configure a retry policy, the default retry policy is used. 
clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
TimeseriesClient client = new TimeseriesClient(endPoint, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

HTTPS

Upgrade to Java 7 for connection based on HTTPS.

Multithreading

Multithreading is supported.
We recommend that you use the same OTSClient object to run multithreading tasks.