Use the HTTP-based SQL API of LindormTSDB - Lindorm - Centre de documentation Alibaba Cloud

LindormTSDB expose une API SQL basée sur HTTP qui accepte les instructions SQL standard via des requêtes HTTP POST. Utilisez cette API pour créer des bases de données et des tables de séries temporelles, écrire des données et exécuter des requêtes depuis n'importe quelle application non-Java, sans installer de bibliothèque cliente.

Remarque

Pour les applications Java, utilisez le pilote JDBC à la place. Les instances Lindorm à nœud unique ne prennent pas en charge l'API SQL HTTP.

Fonctionnement

Toutes les requêtes sont envoyées à un seul endpoint via la méthode HTTP POST. L'instruction SQL figure dans le corps de la requête. L'API renvoie une réponse au format JSON.

POST /api/v2/sql   (port 8242)

La méthode POST est obligatoire pour tous les types d'instructions, y compris SELECT.

Si l'authentification est activée, ajoutez un en-tête d'authentification Basic. Vous pouvez également transmettre des paramètres de requête pour définir la base de données cible ou diffuser de grands jeux de résultats par blocs.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un endpoint d'instance LindormTSDB (format : ld-<instance-id>-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242)
Un accès réseau au port 8242 sur l'endpoint
(Si l'authentification est activée) Un nom d'utilisateur et un mot de passe valides

Envoyer une requête

Endpoint

Chemin	Méthode	Description
`/api/v2/sql`	POST	Exécute une instruction SQL

Format de la requête

Incluez l'instruction SQL dans le corps de la requête. Définissez Content-Type: text/plain dans l'en-tête de la requête.

Important

Ne terminez pas les instructions SQL par un point-virgule (;). Bien que LindormTSDB prenne en charge les points-virgules comme terminateurs d'instruction SQL-92 en interne, leur ajout dans le corps d'une requête provoque une erreur.

Paramètres de requête

Paramètre	Description	Valeur par défaut
`database`	Base de données sur laquelle exécuter l'instruction SQL. Si l'instruction ne spécifie pas de base de données, LindormTSDB effectue la recherche dans cette base.	`default`
`chunked`	Définissez la valeur sur `true` pour diffuser le jeu de résultats en plusieurs blocs JSON. Utilisez cette option pour les requêtes qui renvoient un grand nombre de lignes afin d'éviter de mettre en mémoire tampon l'intégralité du jeu de résultats.	`false`
`chunk_size`	Nombre maximal de lignes par bloc JSON. Ce paramètre prend effet uniquement lorsque `chunked=true`.	`1000`

Authentification

Si l'authentification utilisateur est activée, ajoutez un en-tête Authorization utilisant l'authentification Basic :

Authorization: Basic <Base64-encoded credentials>

Les identifiants encodés en Base64 correspondent au nom d'utilisateur et au mot de passe séparés par deux-points : username:password.

Par exemple, les identifiants par défaut (root:root) s'encodent comme suit :

Authorization: Basic cm9vdDpyb290

Pour l'encodage spécifique à un langage, reportez-vous à la documentation de la bibliothèque Base64 de votre langage de programmation.

Exemples

Les exemples suivants utilisent curl et couvrent le flux de travail complet : création d'une base de données, création d'une table de séries temporelles, insertion de données et interrogation des données.

Important

Ne terminez pas les instructions SQL par un point-virgule (;) dans le corps de la requête. Cela provoquerait une erreur de requête.

Créer une base de données

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

Une réponse réussie renvoie le code HTTP 200.

Créer une table de séries temporelles

Transmettez la base de données cible en tant que paramètre de requête, ou qualifiez le nom de la table avec le nom de la base de données. Les deux instructions ci-dessous créent la même table :

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

Interroger des données avec authentification

Utilisez -u username:password pour transmettre les identifiants. Assurez-vous que l'utilisateur dispose des autorisations requises sur la table.

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'

Une réponse réussie renvoie le code HTTP 200 avec le jeu de résultats :

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>],
    ...
  ]
}

Une instruction SQL non valide renvoie le code HTTP 400 avec un corps d'erreur :

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

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

Pour obtenir la liste complète des codes d'erreur, consultez la section Codes d'erreur courants.

Paramètres de réponse

Réponse de succès (HTTP 200)

Paramètre	Type	Description
`columns`	Tableau de chaînes	Noms des colonnes dans le jeu de résultats
`metadata`	Tableau de chaînes	Types de données de chaque colonne. Pour connaître les types pris en charge, consultez la section Types de données.
`rows`	Tableau de tableaux	Chaque tableau interne représente une ligne, avec des valeurs correspondant aux `columns`

Réponse d'erreur (HTTP 400)

Paramètre	Type	Description
`code`	int	Code d'erreur
`sqlstate`	String	Code d'état SQL
`message`	String	Message d'erreur

Exemple Python

L'exemple suivant crée une table, insère des lignes et exécute une requête à l'aide de la bibliothèque requests.

Créer une table de séries temporelles

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)

Insérer des données

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)

Interroger des données

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

Lindorm:Utiliser l'API SQL HTTP de LindormTSDB

Fonctionnement

Prérequis

Envoyer une requête

Endpoint

Format de la requête

Paramètres de requête

Authentification

Exemples

Créer une base de données

Créer une table de séries temporelles

Interroger des données avec authentification

Paramètres de réponse

Réponse de succès (HTTP 200)

Réponse d'erreur (HTTP 400)

Exemple Python

Créer une table de séries temporelles

Insérer des données

Interroger des données

Étapes suivantes