Como usar o SDK nativo Java para conectar e usar o LindormTSDB - Lindorm: Central de Documentação do Alibaba Cloud

Use o SDK do LindormTSDB para Java para se conectar ao LindormTSDB e executar suas primeiras operações de escrita e consulta.

Pré-requisitos

Antes de começar, verifique se você tem:

JDK 1.8 ou posterior instalado
LindormTSDB 3.4.7 ou posterior (consulte o Guia de versões do LindormTSDB para verificar sua versão atual e a Atualização de versão secundária para atualizar, se necessário)
Endereço IP do cliente adicionado à lista de permissões do Lindorm
O endpoint do mecanismo de séries temporais

Instale o SDK

Há três métodos de instalação. Recomendamos o Maven para a maioria dos projetos.

Método 1: Maven (recomendado)

Adicione a seguinte dependência à seção dependencies do arquivo pom.xml:

<dependency>
  <groupId>com.aliyun.lindorm</groupId>
  <artifactId>lindorm-tsdb-client</artifactId>
  <version>1.0.4</version>
</dependency>

Nota

Um projeto Maven de exemplo está disponível para download. Baixe o projeto de exemplo para compilar e executar localmente ou use-o como base para seu próprio projeto.

Todas as versões do SDK estão disponíveis no repositório central do Maven. Para obter detalhes sobre as versões, consulte o guia de versões do SDK.

Método 2: Pacote JAR no Eclipse

Baixe o pacote do SDK Java e descompacte-o.
No Eclipse, clique com o botão direito do mouse no projeto e selecione Properties.
Clique em Java Build Path > Libraries > Add JARs, selecione lindorm-tsdb-client-1.0.0.jar e todos os pacotes JAR no diretório lib e clique em Apply and Close.

Método 3: Pacote JAR no IntelliJ IDEA

Baixe o pacote do SDK Java e descompacte-o.
No IntelliJ IDEA, clique em File > Project Structure.
No painel de navegação à esquerda, selecione Project Structure > Modules.
Clique em e selecione JARs or directories.
Selecione lindorm-tsdb-client-1.0.0.jar e todos os pacotes JAR no diretório lib e clique em OK.
Clique em Apply e em OK.

Conecte-se ao LindormTSDB

Crie um LindormTSDBClient passando o endpoint do mecanismo de séries temporais para ClientOptions. O cliente é thread-safe. Crie uma única instância e reutilize-a em toda a aplicação.

String url = "http://ld-bp17j28j2y7pm****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242";
// LindormTSDBClient is thread-safe. Create it once and reuse it.
ClientOptions options = ClientOptions.newBuilder(url).build();
LindormTSDBClient lindormTSDBClient = LindormTSDBFactory.connect(options);

Substitua a URL pelo endpoint real do mecanismo de séries temporais.

Crie um banco de dados e uma tabela

Crie um banco de dados chamado demo e uma tabela de séries temporais chamada sensor. Para ver a sintaxe SQL completa, consulte CREATE DATABASE e CREATE TABLE.

lindormTSDBClient.execute("CREATE DATABASE demo");
lindormTSDBClient.execute("demo", "CREATE TABLE sensor (" +
    "device_id VARCHAR TAG, " +
    "region VARCHAR TAG, " +
    "time BIGINT, " +
    "temperature DOUBLE, " +
    "humidity DOUBLE, " +
    "PRIMARY KEY(device_id))");

Escreva dados

O LindormTSDBClient oferece dois modos de escrita:

Modo	Método	Quando usar
Assíncrono (padrão)	`write()` retorna `CompletableFuture<WriteResult>`	Cargas de trabalho de produção com alto throughput; o cliente agrupa as escritas automaticamente
Síncrono	Chame `future.join()` no future retornado	Scripts, operações únicas ou quando for necessário confirmar cada escrita antes de prosseguir

Crie uma lista de objetos Record e chame write():

int numRecords = 10;
List<Record> records = new ArrayList<>(numRecords);
long currentTime = System.currentTimeMillis();

for (int i = 0; i < numRecords; i++) {
    Record record = Record
        .table("sensor")
        .time(currentTime + i * 1000)
        .tag("device_id", "F07A1260")
        .tag("region", "north-cn")
        .addField("temperature", 12.1 + i)
        .addField("humidity", 45.0 + i)
        .build();
    records.add(record);
}

// Asynchronous write — handle the result in the callback
CompletableFuture<WriteResult> future = lindormTSDBClient.write("demo", records);
future.whenComplete((r, ex) -> {
    if (ex != null) {
        System.out.println("Failed to write.");
        Throwable throwable = ExceptionUtils.getRootCause(ex);
        if (throwable instanceof LindormTSDBException) {
            LindormTSDBException e = (LindormTSDBException) throwable;
            System.out.println("Error Code: " + e.getCode());
            System.out.println("SQL State:  " + e.getSqlstate());
            System.out.println("Error Message: " + e.getMessage());
        } else {
            throwable.printStackTrace();
        }
    } else {
        System.out.println("Write successfully.");
    }
});

// To block until the write completes, call join()
System.out.println(future.join());

Consulte dados

Execute consultas SQL com query(). Os resultados são retornados em lotes de 1.000 linhas por padrão. Itere com resultSet.next() até que o método retorne null e feche o ResultSet para liberar recursos de I/O.

String sql = "select * from sensor limit 10";
ResultSet resultSet = lindormTSDBClient.query("demo", sql);

try {
    QueryResult result;
    // next() returns null when all rows have been read
    while ((result = resultSet.next()) != null) {
        List<String> columns = result.getColumns();
        System.out.println("columns: " + columns);
        List<String> metadata = result.getMetadata();
        System.out.println("metadata: " + metadata);
        List<List<Object>> rows = result.getRows();
        for (int i = 0, size = rows.size(); i < size; i++) {
            System.out.println("row #" + i + " : " + rows.get(i));
        }
    }
} finally {
    // Always close the ResultSet to release I/O resources
    resultSet.close();
}

Para obter mais opções de consulta SQL, consulte Consultas básicas.

Exemplo de código completo

import com.aliyun.lindorm.tsdb.client.ClientOptions;
import com.aliyun.lindorm.tsdb.client.LindormTSDBClient;
import com.aliyun.lindorm.tsdb.client.LindormTSDBFactory;
import com.aliyun.lindorm.tsdb.client.exception.LindormTSDBException;
import com.aliyun.lindorm.tsdb.client.model.QueryResult;
import com.aliyun.lindorm.tsdb.client.model.Record;
import com.aliyun.lindorm.tsdb.client.model.ResultSet;
import com.aliyun.lindorm.tsdb.client.model.WriteResult;
import com.aliyun.lindorm.tsdb.client.utils.ExceptionUtils;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CompletableFuture;

public class QuickStart {

    public static void main(String[] args) {

        // 1. Create a client instance.
        String url = "http://ld-xxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242";
        // LindormTSDBClient is thread-safe. Create it once and reuse it.
        ClientOptions options = ClientOptions.newBuilder(url).build();
        LindormTSDBClient lindormTSDBClient = LindormTSDBFactory.connect(options);

        // 2. Create a database named demo and a table named sensor.
        lindormTSDBClient.execute("CREATE DATABASE demo");
        lindormTSDBClient.execute("demo", "CREATE TABLE sensor (device_id VARCHAR TAG,region VARCHAR TAG,time BIGINT,temperature DOUBLE,humidity DOUBLE,PRIMARY KEY(device_id))");

        // 3. Write data.
        int numRecords = 10;
        List<Record> records = new ArrayList<>(numRecords);
        long currentTime = System.currentTimeMillis();
        for (int i = 0; i < numRecords; i++) {
            Record record = Record
                    .table("sensor")
                    .time(currentTime + i * 1000)
                    .tag("device_id", "F07A1260")
                    .tag("region", "north-cn")
                    .addField("temperature", 12.1 + i)
                    .addField("humidity", 45.0 + i)
                    .build();
            records.add(record);
        }

        CompletableFuture<WriteResult> future = lindormTSDBClient.write("demo", records);
        // Process the asynchronous write result.
        future.whenComplete((r, ex) -> {
            // Handle write failures.
            if (ex != null) {
                System.out.println("Failed to write.");
                Throwable throwable = ExceptionUtils.getRootCause(ex);
                if (throwable instanceof LindormTSDBException) {
                    LindormTSDBException e = (LindormTSDBException) throwable;
                    System.out.println("Caught an LindormTSDBException, which means your request made it to Lindorm TSDB, "
                            + "but was rejected with an error response for some reason.");
                    System.out.println("Error Code: " + e.getCode());
                    System.out.println("SQL State:  " + e.getSqlstate());
                    System.out.println("Error Message: " + e.getMessage());
                } else {
                    throwable.printStackTrace();
                }
            } else {
                System.out.println("Write successfully.");
            }
        });
        // Block until the write completes.
        System.out.println(future.join());

        // 4. Query data.
        String sql = "select * from sensor limit 10";
        ResultSet resultSet = lindormTSDBClient.query("demo", sql);

        try {
            // Results are returned in batches of 1,000 rows by default.
            // next() returns null when all rows have been read.
            QueryResult result;
            while ((result = resultSet.next()) != null) {
                List<String> columns = result.getColumns();
                System.out.println("columns: " + columns);
                List<String> metadata = result.getMetadata();
                System.out.println("metadata: " + metadata);
                List<List<Object>> rows = result.getRows();
                for (int i = 0, size = rows.size(); i < size; i++) {
                    List<Object> row = rows.get(i);
                    System.out.println("row #" + i + " : " + row);
                }
            }
        } finally {
            // Always close the ResultSet to release I/O resources.
            resultSet.close();
        }

        // 5. Shut down the client to release resources.
        lindormTSDBClient.shutdown();
    }
}

Próximos passos

CREATE DATABASE: sintaxe completa para criação de bancos de dados
CREATE TABLE: sintaxe completa para criação de tabelas de séries temporais
Consultas básicas: referência de consultas SQL para o LindormTSDB
Guia de versões do SDK: notas de lançamento do SDK nativo Java