Use the HTTP-based SQL API of LindormTSDB - Lindorm: Central de Documentação do Alibaba Cloud

O LindormTSDB disponibiliza uma API SQL baseada em HTTP que aceita instruções SQL padrão via HTTP POST. Use esta API para criar bancos de dados e tabelas de séries temporais, gravar dados e executar consultas em qualquer aplicação não Java, sem instalar uma biblioteca cliente.

Nota

Para aplicações Java, use o driver JDBC. Instâncias single-node do Lindorm não oferecem suporte à API SQL baseada em HTTP.

Funcionamento

Todas as solicitações são enviadas a um único endpoint via HTTP POST. A instrução SQL deve constar no corpo da requisição. A API retorna JSON.

POST /api/v2/sql   (port 8242)

O método POST é obrigatório para todos os tipos de instrução, inclusive SELECT.

Se a autenticação estiver ativada, adicione um cabeçalho Basic Authentication. Opcionalmente, passe parâmetros de consulta para definir o banco de dados de destino ou transmitir grandes conjuntos de resultados em blocos.

Pré-requisitos

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

Um endpoint de instância do LindormTSDB (formato: ld-<instance-id>-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242)
Acesso de rede à porta 8242 no endpoint
(Se a autenticação estiver ativada) Um nome de usuário e senha válidos

Envio de requisições

Endpoint

Path	Method	Descrição
`/api/v2/sql`	POST	Executa uma instrução SQL

Formato da requisição

Inclua a instrução SQL no corpo da requisição. Defina Content-Type: text/plain no cabeçalho da requisição.

Importante

Não termine instruções SQL com ponto e vírgula (;). Embora o LindormTSDB suporte internamente o ponto e vírgula como terminador de instrução SQL-92, adicionar esse caractere ao corpo da requisição causa erro.

Parâmetros de consulta

Parâmetro	Descrição	Padrão
`database`	Banco de dados onde a instrução SQL será executada. Se a instrução não especificar um banco de dados, o LindormTSDB buscará neste banco.	`default`
`chunked`	Defina como `true` para transmitir o conjunto de resultados em múltiplos blocos JSON. Recomendado para consultas que retornam grande volume de linhas, evitando o buffer completo do resultado na memória.	`false`
`chunk_size`	Número máximo de linhas por bloco JSON. Este parâmetro só tem efeito quando `chunked=true`.	`1000`

Autenticação

Se a autenticação de usuário estiver ativada, adicione um cabeçalho Authorization usando Basic Authentication:

Authorization: Basic <Base64-encoded credentials>

As credenciais codificadas em Base64 correspondem ao nome de usuário e senha unidos por dois pontos: username:password.

Por exemplo, as credenciais padrão (root:root) são codificadas como:

Authorization: Basic cm9vdDpyb290

Para codificação específica de linguagem, consulte a documentação da biblioteca Base64 da sua linguagem de programação.

Exemplos

Os exemplos abaixo usam curl e abrangem todo o fluxo de trabalho: criação de banco de dados, criação de tabela de séries temporais, inserção de dados e consulta.

Importante

Não finalize instruções SQL com ponto e vírgula (;) no corpo da requisição. Isso gera erro na solicitação.

Criar um banco de dados

curl -i -X POST \
  http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql \
  -d 'CREATE DATABASE DB1'

Uma resposta bem-sucedida retorna HTTP 200.

Criar uma tabela de séries temporais

Passe o banco de dados de destino como parâmetro de consulta ou qualifique o nome da tabela com o nome do banco de dados. Ambas as instruções abaixo criam a mesma tabela:

# Using the database query parameter
curl -i -X POST \
  "http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1" \
  -d 'CREATE TABLE SENSOR (device_id VARCHAR TAG, region VARCHAR TAG, time TIMESTAMP, temperature DOUBLE, humidity DOUBLE)'

# Using a fully qualified table name
curl -i -X POST \
  http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql \
  -d 'CREATE TABLE DB1.SENSOR (device_id VARCHAR TAG, region VARCHAR TAG, time TIMESTAMP, temperature DOUBLE, humidity DOUBLE)'

Consultar dados com autenticação

Use -u username:password para passar as credenciais. Certifique-se de que o usuário tenha as permissões necessárias na tabela.

curl -i -X POST \
  -u tsdbuser:password \
  "http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1" \
  -d 'SELECT device_id, region, time, MAX(temperature) as max_t FROM SENSOR WHERE time >= 1619076780000 AND time <= 1619076800000 SAMPLE BY 20s'

Em caso de sucesso, a resposta retorna HTTP 200 com o conjunto de resultados:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "columns": ["device_id", "region", "time", "max_t"],
  "metadata": ["VARCHAR", "VARCHAR", "TIMESTAMP", "DOUBLE"],
  "rows": [
    ["<device_id_value>", "<region_value>", "<timestamp_value>", <numeric_value>],
    ...
  ]
}

Instruções SQL inválidas retornam HTTP 400 com um corpo de erro:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": <error_code>,
  "sqlstate": "<sql_state_code>",
  "message": "<error_message>"
}

Para obter a lista completa de códigos de erro, consulte Códigos de erro comuns.

Parâmetros de resposta

Resposta de sucesso (HTTP 200)

Parâmetro	Tipo	Descrição
`columns`	Array de strings	Nomes das colunas no conjunto de resultados
`metadata`	Array de strings	Tipos de dados de cada coluna. Para tipos suportados, consulte Tipos de dados.
`rows`	Array de arrays	Cada array interno representa uma linha, com valores correspondentes às `columns`

Resposta de erro (HTTP 400)

Parâmetro	Tipo	Descrição
`code`	int	Código de erro
`sqlstate`	String	Código de status SQL
`message`	String	Mensagem de erro

Exemplo em Python

O exemplo a seguir cria uma tabela, insere linhas e executa uma consulta usando a biblioteca requests.

Criar uma tabela de séries temporais

import requests

endpoint = "http://ld-bp1s0vbu8955w****-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql"

sql = """CREATE TABLE sensor (
    device_id VARCHAR NOT NULL,
    region VARCHAR NOT NULL,
    time TIMESTAMP NOT NULL,
    temperature DOUBLE,
    humidity BIGINT,
    PRIMARY KEY(device_id, region, time)
)"""
r = requests.post(endpoint, sql)
print(r.status_code, r.content)

Inserir dados

sql = """INSERT INTO sensor (device_id, region, time, temperature, humidity) VALUES
    ('F07A1260', 'north-cn', '2021-04-22 15:33:00', 12.1, 45),
    ('F07A1260', 'north-cn', '2021-04-22 15:33:10', 13.2, 47),
    ('F07A1260', 'north-cn', '2021-04-22 15:33:20', 10.6, 46),
    ('F07A1261', 'south-cn', '2021-04-22 15:33:00', 18.1, 44),
    ('F07A1261', 'south-cn', '2021-04-22 15:33:10', 19.7, 44)"""
r = requests.post(endpoint, sql)
print(r.status_code, r.content)

Consultar dados

r = requests.post(endpoint, "SELECT * FROM sensor")
print(r.status_code, r.content)

Lindorm:Uso da API SQL baseada em HTTP do LindormTSDB

Funcionamento

Pré-requisitos

Envio de requisições

Endpoint

Formato da requisição

Parâmetros de consulta

Autenticação

Exemplos

Criar um banco de dados

Criar uma tabela de séries temporais

Consultar dados com autenticação

Parâmetros de resposta

Resposta de sucesso (HTTP 200)

Resposta de erro (HTTP 400)

Exemplo em Python

Criar uma tabela de séries temporais

Inserir dados

Consultar dados

Próximos passos