Gunakan API SQL berbasis HTTP dari LindormTSDB - Lindorm

Tema ini menjelaskan definisi dan penggunaan API SQL berbasis HTTP yang disediakan oleh LindormTSDB.

Catatan penggunaan

Untuk aplikasi non-Java, Anda dapat langsung menggunakan API yang dijelaskan dalam tema ini untuk mengirim pernyataan SQL ke LindormTSDB.
Untuk aplikasi Java, kami menyarankan Anda menggunakan driver Java Database Connectivity (JDBC) untuk menghubungkan aplikasi dengan LindormTSDB. Untuk informasi lebih lanjut, lihat Gunakan driver JDBC untuk terhubung dan menggunakan LindormTSDB.
Catatan
Instans Lindorm tunggal tidak mendukung API SQL berbasis HTTP.

Path permintaan dan metode

Path permintaan	Metode	Deskripsi
/api/v2/sql	POST	Mengirim dan mengeksekusi pernyataan SQL.

Konten permintaan

Saat memanggil API sebelumnya, sertakan pernyataan SQL dalam badan permintaan HTTP. Kami menyarankan Anda mengatur Content-Type menjadi text/plain di header permintaan. Kode Python berikut memberikan contoh cara memanggil API /api/v2/sql untuk mengirim pernyataan 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)
)"""

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)

Catatan

LindormTSDB mendukung penggunaan titik koma (;) sebagai terminator pernyataan SQL sesuai standar SQL-92. Namun, saat memanggil API /api/v2/sql, titik koma (;) tidak boleh digunakan di akhir pernyataan SQL. Jika tidak, kesalahan akan dilaporkan selama permintaan.

Parameter kueri yang didukung

Tabel berikut menjelaskan parameter kueri URL yang didukung oleh API /api/v2/sql.

Parameter	Deskripsi
database	Database default tempat pernyataan SQL dieksekusi. Anda dapat meneruskan pernyataan SQL ke permintaan API SQL untuk menulis data ke tabel deret waktu atau menanyakan data dari tabel deret waktu. Jika database tempat tabel deret waktu milik tidak ditentukan dalam pernyataan SQL, LindormTSDB mencari tabel yang ditentukan dalam database yang ditentukan oleh parameter database. Jika Anda tidak menentukan parameter database, LindormTSDB mencari tabel yang ditentukan dalam database bernama `default`.
chunked	Menentukan apakah akan mengembalikan hasil data dalam chunk. Nilai default: false. Jika parameter ini diatur ke true, data hasil kueri dibagi menjadi beberapa blok JSON lalu dikembalikan. Setiap blok JSON berisi maksimal N baris data. N ditentukan oleh parameter chunk_size. Saat aplikasi Anda menerima hasil kueri, itu hanya perlu mengurai blok JSON satu per satu. Untuk informasi lebih lanjut tentang struktur setiap blok JSON, lihat bagian "Parameter respons" dari tema ini.
chunk_size	Jumlah maksimum baris yang dikembalikan pada satu waktu. Parameter ini berlaku saat parameter chunked diatur ke true. Nilai default: 1000.

Tentukan kredensial pengguna untuk informasi autentikasi

Jika autentikasi pengguna diaktifkan untuk LindormTSDB, Anda harus menyertakan informasi autentikasi pengguna di header permintaan HTTP saat menggunakan API /api/v2/sql untuk mengirim kueri SQL. API /api/v2/sql menggunakan metode BASIC AUTH. Informasi autentikasi yang disandikan harus ditentukan di bidang Authorization pada header permintaan HTTP.

Anda dapat menentukan kredensial pengguna dalam format berikut untuk autentikasi dasar:

BASIC {Informasi autentikasi yang disandikan Base64}

Informasi autentikasi yang disandikan Base64 berada dalam format berikut: ${username}:${password}. Nama pengguna dan kata sandi dipisahkan oleh tanda titik dua (:).

Catatan

Untuk informasi lebih lanjut tentang cara menyandikan dan menentukan kredensial pengguna untuk autentikasi dasar menggunakan bahasa pemrograman yang berbeda, lihat dokumentasi untuk pustaka kelas yang relevan dari bahasa pemrograman tersebut.

Sebagai contoh, jika Anda menggunakan nama pengguna dan kata sandi default (keduanya adalah root) sebagai kredensial untuk autentikasi dasar, nilai yang disandikan Base64 dari bidang Authorization di header HTTP adalah Basic cm9vdDpyb290, seperti yang ditunjukkan dalam contoh berikut:

Authorization: Basic cm9vdDpyb290

Parameter respons

Jika permintaan berhasil, kode status HTTP dalam pesan respons adalah 200 dan konten respons dikembalikan dalam format JSON. Tabel berikut menjelaskan parameter respons.

Parameter	Tipe	Deskripsi
columns	Array	Array string. Ini menunjukkan nama setiap kolom dalam set hasil yang dikembalikan.
metadata	Array	Array string. Ini menunjukkan tipe data setiap kolom dalam set hasil yang dikembalikan. Untuk informasi lebih lanjut tentang tipe data yang dikembalikan, lihat Tipe data.
rows	Array	Array dari array. Ini menunjukkan kumpulan baris dalam set hasil yang dikembalikan. Setiap array menunjukkan satu baris data, dan nilai spesifik dalam setiap baris sesuai dengan kolom yang ditunjukkan oleh parameter columns.

Saat terjadi kesalahan eksekusi SQL, kode status HTTP dalam pesan respons adalah 400 dan konten respons dikembalikan dalam format JSON. Tabel berikut menjelaskan parameter.

Parameter	Tipe	Deskripsi
code	int	Kode kesalahan yang dikembalikan.
sqlstate	String	Kode status SQL yang dikembalikan.
message	String	Pesan kesalahan yang dikembalikan.

Catatan

Untuk informasi lebih lanjut tentang kode kesalahan, lihat Kode Kesalahan Umum.

Contoh

Contoh berikut menunjukkan cara memanggil API /api/v2/sql untuk mengeksekusi pernyataan SQL di LindormTSDB. Dalam contoh-contoh tersebut, alat umum curl digunakan.

Buat database bernama DB1.

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

Buat tabel deret waktu bernama SENSOR di DB1. Anda dapat mengeksekusi salah satu dari dua pernyataan berikut untuk membuat tabel:

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

Jika autentikasi pengguna diaktifkan, gunakan akun dengan nama pengguna tsdbuser untuk menanyakan data dalam tabel deret waktu 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'

Catatan

Pastikan bahwa tsdbuser diberi izin yang diperlukan pada tabel deret waktu SENSOR.