Use the HTTP-based SQL API of LindormTSDB - Lindorm - Centro de documentación de Alibaba Cloud

LindormTSDB expone una API SQL basada en HTTP que acepta instrucciones SQL estándar mediante solicitudes HTTP POST. Utilice esta API para crear bases de datos y tablas de series temporales, escribir datos y ejecutar consultas desde cualquier aplicación que no sea Java sin necesidad de instalar una biblioteca cliente.

Nota

Para aplicaciones Java, utilice JDBC driver en su lugar. Las instancias de Lindorm de nodo único no son compatibles con la API SQL basada en HTTP.

Funcionamiento

Todas las solicitudes se envían a un único endpoint mediante HTTP POST. La instrucción SQL se incluye en el cuerpo de la solicitud. La API devuelve una respuesta en formato JSON.

POST /api/v2/sql   (port 8242)

El método POST es obligatorio para todos los tipos de instrucciones, incluidas las de tipo SELECT.

Si la autenticación está habilitada, agregue un encabezado de autenticación básica. De forma opcional, puede pasar parámetros de consulta para especificar la base de datos de destino o transmitir conjuntos de resultados grandes en fragmentos.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Un endpoint de instancia de LindormTSDB (formato: ld-<instance-id>-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242)
Acceso de red al puerto 8242 del endpoint
(Si la autenticación está habilitada) Un nombre de usuario y una contraseña válidos

Envío de una solicitud

Endpoint

Ruta	Método	Descripción
`/api/v2/sql`	POST	Ejecuta una instrucción SQL

Formato de la solicitud

Incluya la instrucción SQL en el cuerpo de la solicitud. Establezca Content-Type: text/plain en el encabezado de la solicitud.

Importante

No finalice las instrucciones SQL con punto y coma (;). Aunque LindormTSDB admite internamente el punto y coma como terminador de instrucciones SQL-92, agregarlo al cuerpo de la solicitud provoca un error.

Parámetros de consulta

Parámetro	Descripción	Valor predeterminado
`database`	La base de datos donde se ejecutará la instrucción SQL. Si la instrucción no especifica una base de datos, LindormTSDB buscará en esta.	`default`
`chunked`	Establézcalo en `true` para transmitir el conjunto de resultados en varios bloques JSON. Utilícelo en consultas que devuelven grandes cantidades de filas para evitar almacenar en búfer todo el conjunto de resultados en memoria.	`false`
`chunk_size`	Número máximo de filas por bloque JSON. Solo tiene efecto cuando `chunked=true`.	`1000`

Autenticación

Si la autenticación de usuarios está habilitada, agregue un encabezado Authorization mediante autenticación básica:

Authorization: Basic <Base64-encoded credentials>

Las credenciales codificadas en Base64 consisten en el nombre de usuario y la contraseña unidos por dos puntos: username:password.

Por ejemplo, las credenciales predeterminadas (root:root) se codifican de la siguiente manera:

Authorization: Basic cm9vdDpyb290

Para obtener información sobre la codificación específica de cada lenguaje, consulte la documentación de la biblioteca Base64 correspondiente a su lenguaje de programación.

Ejemplos

Los siguientes ejemplos utilizan curl y abarcan el flujo de trabajo completo: creación de una base de datos, creación de una tabla de series temporales, inserción de datos y consulta de datos.

Importante

No finalice las instrucciones SQL con punto y coma (;) en el cuerpo de la solicitud, ya que esto provoca un error.

Creación de una base de datos

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

Una respuesta exitosa devuelve un código HTTP 200.

Creación de una tabla de series temporales

Pase la base de datos de destino como parámetro de consulta o califique el nombre de la tabla con el nombre de la base de datos. Ambas instrucciones siguientes crean la misma tabla:

# 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)'

Consulta de datos con autenticación

Utilice -u username:password para pasar las credenciales. Asegúrese de que el usuario tenga los permisos necesarios sobre la tabla.

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'

Una respuesta exitosa devuelve un código HTTP 200 junto con el 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>],
    ...
  ]
}

Una instrucción SQL no válida devuelve un código HTTP 400 con un cuerpo de error:

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

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

Para consultar la lista completa de códigos de error, consulte Common error codes.

Parámetros de respuesta

Respuesta exitosa (HTTP 200)

Parámetro	Tipo	Descripción
`columns`	Matriz de cadenas	Nombres de las columnas en el conjunto de resultados
`metadata`	Matriz de cadenas	Tipos de datos de cada columna. Para ver los tipos compatibles, consulte Data types.
`rows`	Matriz de matrices	Cada matriz interna representa una fila, con valores correspondientes a `columns`

Respuesta de error (HTTP 400)

Parámetro	Tipo	Descripción
`code`	int	Código de error
`sqlstate`	String	Código de estado SQL
`message`	String	Mensaje de error

Ejemplo en Python

El siguiente ejemplo crea una tabla, inserta filas y ejecuta una consulta mediante la biblioteca requests.

Creación de una tabla de series temporales

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)

Inserción de datos

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)

Consulta de datos

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

Lindorm:Uso de la API SQL basada en HTTP de LindormTSDB

Funcionamiento

Requisitos previos

Envío de una solicitud

Endpoint

Formato de la solicitud

Parámetros de consulta

Autenticación

Ejemplos

Creación de una base de datos

Creación de una tabla de series temporales

Consulta de datos con autenticación

Parámetros de respuesta

Respuesta exitosa (HTTP 200)

Respuesta de error (HTTP 400)

Ejemplo en Python

Creación de una tabla de series temporales

Inserción de datos

Consulta de datos

Pasos siguientes