Lindorm:LindormTSDB の HTTP ベース SQL API の使用

使用上の注意

• Java 以外のアプリケーションを開発する場合は、このトピックで説明されている API を直接使用して、SQL ステートメントを LindormTSDB に送信できます。

• Java アプリケーションを開発する場合は、Java Database Connectivity（JDBC）ドライバーを使用して、アプリケーションを LindormTSDB に接続することをお勧めします。詳細については、「JDBC ドライバーを使用した LindormTSDB への接続と使用」をご参照ください。

  説明

  シングルノード Lindorm インスタンスは、HTTP ベースの SQL API をサポートしていません。

リクエストパスとメソッド

リクエストコンテンツ

上記の API を呼び出すときは、HTTP リクエストの本文に SQL ステートメントを含めます。Content-Type をリクエストヘッダーで text/plain に設定することをお勧めします。次の Python コードは、/api/v2/sql API を呼び出して SQL ステートメントを送信する方法の例を示しています。

import requests

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

payload = """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)
)"""
# SQLステートメントを送信

r = requests.post(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

payload = """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(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

payload = "select * from sensor"
# データをクエリ

r = requests.post(url, payload)
if r.status_code == 200:
    print(r.content)
else:
    print(r.content)

サポートされているクエリパラメーター

次の表は、/api/v2/sql API でサポートされている URL クエリパラメーターについて説明しています。

認証情報にユーザー資格情報を指定する

LindormTSDB でユーザー認証が有効になっている場合は、/api/v2/sql API を使用して SQL クエリを送信するときに、HTTP リクエストヘッダーにユーザーの認証情報を含める必要があります。/api/v2/sql API は、BASIC AUTH メソッドを使用します。エンコードされた認証情報は、HTTP リクエストヘッダーの Authorization フィールドで指定する必要があります。

基本認証では、次の形式でユーザー資格情報を指定できます。

BASIC {Base64 エンコードされた認証情報}

Base64 エンコードされた認証情報は、${username}:${password} の形式です。ユーザー名とパスワードはコロン（:）で区切ります。

たとえば、デフォルトのユーザー名とパスワード（どちらも root）を基本認証の資格情報として使用する場合は、HTTP ヘッダーの Authorization フィールドの Base64 エンコード値は Basic cm9vdDpyb290 になります。次の例を参照してください。

Authorization: Basic cm9vdDpyb290

レスポンスパラメーター

リクエストが成功した場合、レスポンスメッセージの HTTP ステータスコードは 200 で、レスポンスコンテンツは JSON 形式で返されます。次の表は、レスポンスパラメーターについて説明しています。

SQL 実行エラーが発生した場合、レスポンスメッセージの HTTP ステータスコードは 400 で、レスポンスコンテンツは JSON 形式で返されます。次の表は、パラメーターについて説明しています。

例

次の例は、/api/v2/sql API を呼び出して LindormTSDB で SQL ステートメントを実行する方法を示しています。例では、一般的なツール curl を使用しています。

• DB1 という名前のデータベースを作成します。

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

• DB1 に SENSOR という名前の時系列テーブルを作成します。次の 2 つのステートメントのいずれかを実行して、テーブルを作成できます。

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

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

• ユーザー認証が有効になっている場合は、ユーザー名が tsdbuser のアカウントを使用して、SENSOR 時系列テーブルのデータをクエリします。

  curl -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'

  説明

  tsdbuser に SENSOR 時系列テーブルに対する必要な権限が付与されていることを確認してください。