全部产品
Search
文档中心

表格存储:初始化OTSClient

更新时间:Jul 01, 2024

OTSClient是表格存储服务的客户端,它为调用者提供了一系列的方法,可以用来操作表、读写单行数据、读写多行数据等。如果要使用宽表模型的操作数据表、读写单行数据、读写多行数据等功能,您需要初始化一个OTSClient实例,并可以根据需要修改OTSClientConfig的默认配置项;如果要使用时序模型的操作时序表、检索时间线、读写时序数据等功能,您需要初始化一个TimeseriesClient实例。

注意事项

  • 如果要使用HTTPs协议访问表格存储资源,请升级Java环境到Java 7后即可。

  • 表格存储Java SDK支持使用多线程。使用多线程时,建议共用一个OTSClient对象。

准备工作

初始化OTSClient前,您需要完成配置访问密钥、获取实例Endpoint和安装表格存储Java SDK的准备工作。

配置访问密钥

要接入阿里云的表格存储服务,您需要拥有一个有效的访问密钥进行签名认证。目前支持如下三种方式获取AccessKey。为了保证访问密钥安全,请根据使用的操作系统将访问密钥配置到环境变量。

  1. 获取访问密钥。

    重要

    为避免阿里云账号泄露AccessKey带来的安全风险,建议您通过RAM用户来完成授权和AccessKey的创建。

    获取方式

    操作

    阿里云账号的AccessKey ID和AccessKey Secret

    1. 在阿里云官网注册阿里云账号

    2. 创建AccessKey ID和AccessKey Secret。具体操作,请参见创建AccessKey

    被授予访问表格存储权限RAM用户的AccessKey ID和AccessKey Secret

    1. 使用阿里云账号前往访问控制RAM,创建一个新的RAM用户或者使用已经存在的RAM用户。

    2. 使用阿里云账号授予RAM用户访问表格存储的权限。具体操作,请参见通过RAM Policy为RAM用户授权

    3. 为RAM用户授权后,即可使用RAM用户的AccessKey ID和AccessKey Secret访问。具体操作,请参见创建AccessKey

    从STS获取的临时访问凭证

    1. 应用的服务器通过访问RAM/STS服务,获取一个临时的AccessKey ID、AccessKey Secret和SecurityToken发送给使用方。

    2. 使用方使用上述临时密钥访问表格存储服务。

  2. 配置环境变量。

    表格存储使用OTS_AK_ENV环境变量名表示阿里云账号或者RAM用户的AccessKey ID,使用OTS_SK_ENV环境变量名表示对应AccessKey Secret,请根据实际配置。

    重要

    环境变量配置完成后,为确保新的设置被正确应用,您可能需要重启相关的开发工具(IDE等)或服务。

    Windows系统配置方法

    您可以通过图形用户界面GUI、命令行提示符CMD或Windows PowerShell的方式进行环境变量的配置。更多信息,请参见在Linux、macOS和Windows系统配置环境变量

    通过图形用户界面GUI配置

    通过图形化界面方式在环境变量对话框的系统变量区域中分别添加环境变量OTS_AK_ENV和OTS_SK_ENV,并将环境变量分别配置为已准备好的AccessKey ID和AccessKey Secret,然后保存配置即可。

    通过命令行提示符CMD配置

    以管理员身份打开命令提示符,并使用以下命令在系统中新增环境变量。其中/M表示系统级环境变量。

    setx OTS_AK_ENV LT******************** /M
    setx OTS_SK_ENV Ir**************************** /M

    配置完成后,在命令提示符界面执行echo %OTS_AK_ENV%echo %OTS_SK_ENV%命令检查配置是否生效。如果能返回正确的AccessKey,则说明配置成功。

    通过Windows PowerShell配置

    1. 以管理员身份运行Windows PowerShell。

    2. 在PowerShell中执行如下命令设置环境变量。

      [System.Environment]::SetEnvironmentVariable('OTS_AK_ENV', 'LT********************', [System.EnvironmentVariableTarget]::Machine)
      [System.Environment]::SetEnvironmentVariable('OTS_SK_ENV', 'Ir****************************', [System.EnvironmentVariableTarget]::Machine)
    3. 重启PowerShell后,在PowerShell中执行如下命令验证环境变量是否生效。

      如果返回正确的AccessKey,则说明配置成功。

      Get-ChildItem env:OTS_AK_ENV
      Get-ChildItem env:OTS_SK_ENV

    Linux和macOS系统配置方法

    说明

    如果是第一次设置环境变量,您可以使用touch ~/.bash_profile命令创建一个配置文件,如果已经存在配置文件,则使用vim ~/.bash_profile命令直接编辑文件。

    1. 创建.bash_profile文件。

      touch ~/.bash_profile
      vim ~/.bash_profile
    2. .bash_profile文件中配置环境变量,编辑完成后保存退出。

      # 将以下命令中的<ACCESS_KEY_ID>请替换为已准备好的AccessKey ID,<ACCESS_KEY_SECRET>请替换为对应的AccessKey Secret。
      export OTS_AK_ENV=<ACCESS_KEY_ID>
      export OTS_SK_ENV=<ACCESS_KEY_SECRET>
    3. 使用.bash_profile文件的配置生效并进行验证。

      # 使配置文件生效
      source ~/.bash_profile
      # 显示配置是否生效
      echo $ALIBABA_CLOUD_ACCESS_KEY_ID

      如果返回正确的AccessKey ID,则说明配置成功。

获取实例Endpoint

创建实例后,您需要获取实例域名地址(Endpoint)用于后续通过Endpoint访问实例。

Endpoint是阿里云表格存储服务各个实例的域名地址,例如https://sun.cn-hangzhou.ots.aliyuncs.com,表示使用HTTPS协议通过公网网络访问华东1(杭州)地域的sun实例。更多信息,请参见服务地址

重要

除了公网可以访问外,也支持私网地址。

  1. 如果未开通表格存储服务,请进行开通。具体操作,请参见开通表格存储服务

  2. 创建实例。具体操作,请参见创建实例

  3. 创建实例后获取实例的Endpoint。

    1. 登录表格存储控制台

    2. 概览页面,单击实例名称。

    3. 实例详情页签的实例访问地址区域即可查看该实例的服务地址(Endpoint)。

      fig_endpoint

安装表格存储Java SDK

具体操作,请参见安装表格存储Java SDK

初始化Client

如果要使用宽表模型,在使用表格存储的SDK时,您必须首先构造一个Client,通过调用该Client的接口来访问表格存储服务,Client的接口与表格存储提供的RestfulAPI是一致的。

表格存储的SDK提供了SyncClient和AsyncClient两种Client,分别对应同步接口和异步接口。同步接口调用完毕后请求即执行完成,使用方便,用户可以先使用同步接口了解表格存储的各种功能。异步接口相比同步接口更加灵活,如果对性能有一定需求,可以在使用异步接口和使用多线程之间做一些取舍。

说明

不管是SyncClient还是AsyncClient,都是线程安全的,且内部会自动管理线程和管理连接资源。不需要为每个线程创建一个Client,也不需要为每个请求创建一个Client,全局创建一个Client即可。

获取到AccessKey ID和AccessKey Secret后,您可以按照如下示例代码初始化Client。

重要

阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。本示例以将AccessKey保存在环境变量中来实现身份验证为例介绍。

为了进一步保证用户密钥的安全,表格存储支持在初始化客户端时使用V4签名算法对用户密钥进行保护,推荐您使用V4签名进行客户端初始化。

说明

关于使用V4签名的更多信息,请参见用户密钥安全

V4签名

表格存储Java SDK从5.16.1版本开始支持V4签名功能。使用V4签名前,请确保已使用支持该功能的SDK版本。

String region = "";
String endPoint = "";
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
String instanceName = "";
/**
 *  构造V4签名的信任凭证。
 */
DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);
/**
 * 使用V4签名信任凭证构造OTSClient。
 */
SyncClient client = new SyncClient(endPoint, provider, instanceName, null, new ResourceManager(null, null));

配置参数说明请参见下表。

参数

示例

说明

region

cn-hangzhou

实例所处地域的ID。更多信息,请参见地域

endPoint

https://myinstance.cn-hangzhou.ots.aliyuncs.com

实例的访问地址。具体操作,请参见获取实例Endpoint

accessKeyId

System.getenv("OTS_AK_ENV")

通过环境变量获取AccessKey。

请确保已配置相应环境变量。具体操作,请参见配置访问密钥

accessKeySecret

System.getenv("OTS_SK_ENV")

instanceName

myinstance

实例名称。更多信息,请参见实例

非V4签名

创建SyncClient时支持使用默认配置或者自定义配置,请根据实际选择。

  • 使用默认配置创建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);                        

    配置参数说明请参见下表。

    参数

    示例

    说明

    endPoint

    https://myinstance.cn-hangzhou.ots.aliyuncs.com

    实例的访问地址。具体操作,请参见获取实例Endpoint

    accessKeyId

    System.getenv("OTS_AK_ENV")

    通过环境变量获取AccessKey。

    请确保已配置相应环境变量。具体操作,请参见配置访问密钥

    accessKeySecret

    System.getenv("OTS_SK_ENV")

    instanceName

    myinstance

    实例名称。更多信息,请参见实例

  • 使用自定义配置创建SyncClient

    // ClientConfiguration提供了很多配置项,以下只列举部分。
    ClientConfiguration clientConfiguration = new ClientConfiguration();
    // 设置建立连接的超时时间。单位为毫秒。
    clientConfiguration.setConnectionTimeoutInMillisecond(5000);
    // 设置socket超时时间。单位为毫秒。
    clientConfiguration.setSocketTimeoutInMillisecond(5000);
    // 设置重试策略。如果不设置,则采用默认的重试策略。
    clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
    SyncClient client = new SyncClient(endPoint, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

初始化TimeseriesClient

如果要使用时序模型,在使用表格存储的SDK时,您需要初始化一个TimeseriesClient实例,通过调用该TimeseriesClient的接口来访问表格存储服务。时序模型需要初始化单独的Client。

表格存储的SDK提供了TimeseriesClient和AsyncTimeseriesClient两种TimeseriesClient,分别对应同步接口和异步接口。

获取到AccessKey ID和AccessKey Secret后,您可以按照如下示例代码初始化TimeseriesClient。

使用默认配置创建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);

配置参数说明请参见下表。

参数

示例

说明

endPoint

https://myinstance.cn-hangzhou.ots.aliyuncs.com

实例的访问地址。具体操作,请参见获取实例Endpoint

accessKeyId

System.getenv("OTS_AK_ENV")

通过环境变量获取AccessKey。

请确保已配置相应环境变量。具体操作,请参见配置访问密钥

accessKeySecret

System.getenv("OTS_SK_ENV")

instanceName

myinstance

实例名称。更多信息,请参见实例

使用自定义配置创建TimeseriesClient

// ClientConfiguration提供了很多配置项,以下只列举部分。
ClientConfiguration clientConfiguration = new ClientConfiguration();
// 设置建立连接的超时时间。单位为毫秒。
clientConfiguration.setConnectionTimeoutInMillisecond(5000);
// 设置socket超时时间。单位为毫秒。
 clientConfiguration.setSocketTimeoutInMillisecond(5000);
// 设置重试策略。如果不设置,则采用默认的重试策略。
clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
TimeseriesClient client = new TimeseriesClient(endPoint, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

常见问题