# HTTP API経由でEMQX Tablesにアクセスする EMQX Tablesは、Dedicated（レガシー）およびServerlessのデプロイメントユーザーがHTTPリクエストを通じて直接データの挿入やクエリを実行できるHTTP APIインターフェースを提供しています。これは、MQTTやSDKベースの方法ではなく、シンプルなHTTP統合を好むアプリケーションやスクリプトに便利です。 HTTP APIは複数のプロトコルをサポートしています： - **SQL**：データのクエリや挿入のためのSQL文を実行します。 - **PromQL**：Prometheus Query Language（PromQL）を使ったデータクエリ。 - **InfluxDB Line Protocol**：InfluxDB互換のラインフォーマットでデータを書き込みます。 ## HTTP経由のSQL ### ベースURL HTTP APIは、EMQX Tablesのデプロイメント概要ページの**Connection Info**セクションに記載されたホストアドレスを使用します。 HTTPSプロトコルのポート443（デフォルト、指定不要）を使用します。 例： ``` https://k81a5888.ala.us-east-1.aws.emqxtables.com ``` すべてのSQL関連リクエストは以下のエンドポイントに送信されます： ```bash /v1/sql ``` 例： ```bash https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/sql ``` ### 必須ヘッダー EMQX Tables HTTP APIへのリクエストには認証およびデータ形式を扱うための特定のヘッダーが必要です。以下の例はすべてHTTPSプロトコルを使用しています。 #### 認証 EMQX Tables HTTP APIはBasic認証を使用します。 リクエストに以下のヘッダーを追加してください： ```sql Authorization: Basic ``` - **username** と **password** はEMQX CloudコンソールのEMQX Tables **Deployment Overview** ページ内の **Connection Info** セクションで確認できます。 - これらの認証情報は各デプロイメント固有で、すべてのAPIアクセスに必須です。 Base64エンコード文字列の作成方法： 1. ユーザー名とパスワードをコロンで連結します： ``` username:password ``` 2. その文字列をBase64でエンコードします。 例： ``` Username: k81a5888q2aa1077 Password: p11cb3e282a77af1 ``` Base64エンコード後： ``` azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx ``` ヘッダーは以下のようになります： ``` Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx ``` #### その他のヘッダー | ヘッダー名 | 説明 | 例 | | ------------------------ | ------------------------------------------------------------ | --------------------------------------------------- | | **Content-Type** | リクエストボディはフォームエンコード形式である必要があります。 | `Content-Type: application/x-www-form-urlencoded` | | **X-Greptime-Timeout** | *(任意)* サーバー側のクエリタイムアウトを設定します。 | `X-Greptime-Timeout: 120s` | | **X-Greptime-Timezone** | *(任意)* 時間関連のSQL操作に使用するタイムゾーンを設定します。 | `X-Greptime-Timezone: +1:00` | ### クエリパラメータ 出力形式やデータベースコンテキストを制御するためのオプションのクエリ文字列パラメータを指定できます。 | パラメータ | 説明 | デフォルト | 備考 | | ---------- | ---------------------------- | ---------------- | ------------------------------------------------------------ | | `db` | 対象データベース名を指定します。 | `public` | 任意 | | `format` | 出力形式を指定します。 | `greptimedb_v1` | 任意。レスポンス形式を制御します。以下の対応形式を参照してください。 | **対応フォーマット一覧：** - `greptimedb_v1`：デフォルトのJSON出力形式。 - `influxdb_v1`：InfluxDB互換のクエリレスポンス。 - 追加パラメータ：`epoch`（`[ns, u, µ, ms, s, m, h]`）でタイムスタンプの精度を指定。 - `csv`：ヘッダーなしのカンマ区切り値で出力。 - `csvWithNames`：カラム名ヘッダー付きのカンマ区切り値で出力。 - `csvWithNamesAndTypes`：カラム名とデータ型ヘッダー付きのカンマ区切り値で出力。 - `arrow`：Apache Arrow IPC形式 - 追加パラメータ：`compression`（`zstd`または`lz4`）、デフォルトは無圧縮。 - `table`：コンソール出力向けのASCIIテーブル形式。 - `null`：行数と経過時間のみを簡潔にテキスト出力。クエリ性能評価に便利。 ### SQL文の実行 `POST`メソッドを使用し、`application/x-www-form-urlencoded`のContent-Typeで送信します。このContent-Typeはリクエストボディが単純なキー・バリューのペアでエンコードされることを意味します： - **キー**：sql - **値**：実行するSQL文 例： ```sql sql=SHOW TABLES ``` ### SQL文の例 #### 例1：すべてのテーブル一覧を取得 `public`データベース内のすべてのテーブルを一覧表示する`SHOW TABLES`文の実行例です。 **リクエスト** ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/sql Content-Type: application/x-www-form-urlencoded Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx sql=SHOW TABLES ``` **レスポンス** ```json { "output": [ { "records": { "schema": { "column_schemas": [ { "name": "Tables", "data_type": "String" } ] }, "rows": [ ["sensor_temperature_humidity"] ], "total_rows": 1 } } ], "execution_time_ms": 4 } ``` #### 例2：レコードの挿入 `sensor_temperature_humidity`テーブルに新しいデータ行を`INSERT INTO`文で挿入する例です。 **リクエスト** ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/sql Content-Type: application/x-www-form-urlencoded Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx sql=INSERT INTO sensor_temperature_humidity(device_id, temperature, humidity, ts) VALUES ('sensors001', 42.0, 42.0, now()) ``` **レスポンス** ```json { "output": [ { "affectedrows": 1 } ], "execution_time_ms": 2 } ``` #### 例3：データのクエリ（デフォルトJSON出力） `sensor_temperature_humidity`テーブルのすべてのデータをクエリし、デフォルトのJSON形式で結果を返す例です。 **リクエスト** ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/sql Content-Type: application/x-www-form-urlencoded Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx sql=SELECT * FROM sensor_temperature_humidity ``` **レスポンス** ```json { "output": [ { "records": { "schema": { "column_schemas": [ { "name": "device_id", "data_type": "String" }, { "name": "temperature", "data_type": "Float64" }, { "name": "humidity", "data_type": "Float64" }, { "name": "ts", "data_type": "TimestampMillisecond" } ] }, "rows": [ ["sensors001", 42.0, 42.0, 1764150607785] ], "total_rows": 1, "metrics": { "greptime_cloud_rcu": 1 } } } ], "execution_time_ms": 3 } ``` #### 例4：データのクエリ（CSV出力） `sensor_temperature_humidity`テーブルのすべてのデータをクエリし、CSV形式で結果を返す例です。 **リクエスト** ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/sql?format=csv Content-Type: application/x-www-form-urlencoded Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx sql=SELECT * FROM sensor_temperature_humidity ``` **レスポンス** ```json sensors001,42.0,42.0,1764150607785 ``` ### 注意事項 - **デフォルトデータベース**：`db`がクエリ文字列で指定されない場合、すべてのSQLクエリは`public`データベースを対象とします。 - **タイムアウト**：長時間実行されるクエリは`X-Greptime-Timeout`で早期終了させることが可能です。 - **タイムゾーン**：`X-Greptime-Timezone`を使ってタイムスタンプの解釈および返却を制御します。 - **セキュリティ**：常にHTTPSを使用し、認証情報の平文共有は避けてください。 - **レスポンス時間**：`execution_time_ms`フィールドはサーバー側のクエリ実行時間を示します。 ## HTTP経由のPromQL EMQX TablesはPrometheus Query Language（PromQL）を使った時系列データのクエリをHTTP APIでサポートしています。 利用可能なPromQL互換APIは2種類あります： 1. **Prometheus互換API**：標準のPrometheusレスポンス形式で結果を返します。 2. **GreptimeDB JSON出力API**：SQL APIと同様のデータフレームJSON形式で結果を返します。 両方ともHTTPSとBasic認証をサポートしています。 ### Prometheus互換PromQL API #### エンドポイント EMQX Tablesは以下のPrometheus互換クエリAPIを`/v1/prometheus/api/v1`配下に公開しています： | 操作 | エンドポイント | | -------------- | ------------------------------------------------- | | インスタントクエリ | `/v1/prometheus/api/v1/query` | | 範囲クエリ | `/v1/prometheus/api/v1/query_range` | | シリーズ取得 | `/v1/prometheus/api/v1/series` | | ラベル名取得 | `/v1/prometheus/api/v1/labels` | | ラベル値取得 | `/v1/prometheus/api/v1/label//values` | すべてのエンドポイントは**GET**および**POST**をサポートします。 #### 必須ヘッダー | ヘッダー名 | 説明 | | -------------------- | ------------------------------------------------------------ | | **Authorization** | SQL APIと同様：`Authorization: Basic ` | | **Content-Type** | POSTリクエスト時のみ必須：`application/x-www-form-urlencoded` | #### クエリパラメータ | パラメータ | 説明 | デフォルト | | ---------- | -------------- | ----------- | | `db` | データベース名 | `public` | その他のクエリパラメータはPrometheus仕様に準拠します： - **GET**リクエストの場合：URLエンコードされたクエリパラメータを使用します。詳細は[Prometheusドキュメント](https://prometheus.io/docs/prometheus/latest/querying/api/)を参照してください。 - **POST**リクエストの場合：`application/x-www-form-urlencoded`形式のボディでパラメータを送信します。 #### リクエストボディ（POST） POSTリクエストでは、PromQLパラメータをフォームエンコードされたキー・バリュー形式で含めます。 例となるキー： - `query` - `start` - `end` - `step` #### 例：範囲クエリ（60秒ステップ） 10分間の期間における温度値をクエリします。 ##### リクエスト ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/prometheus/api/v1/query_range Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx Content-Type: application/x-www-form-urlencoded query=sensor_temperature start=2025-11-28T10:00:00Z end=2025-11-28T10:10:00Z step=60s ``` ##### レスポンス（200 OK） ```json { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "__name__": "sensor_temperature", "device_id": "sensor_1" }, "values": [ [ 1764324000.0, "22.5" ], [ 1764324060.0, "22.600000381469727" ], [ 1764324120.0, "22.700000762939453" ], [ 1764324180.0, "22.799999237060547" ], [ 1764324240.0, "22.899999618530273" ], [ 1764324300.0, "23" ], [ 1764324360.0, "23.100000381469727" ], [ 1764324420.0, "23.200000762939453" ], [ 1764324480.0, "23.299999237060547" ], [ 1764324540.0, "23.399999618530273" ], [ 1764324600.0, "23.399999618530273" ] ] } ] } } ``` #### 例：`irate()`を用いた範囲クエリ（3分ウィンドウ） 3分の計算ウィンドウと60秒ステップで温度の増加率をクエリします。 ##### リクエスト ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/prometheus/api/v1/query_range Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx Content-Type: application/x-www-form-urlencoded query=irate(sensor_temperature[3m]) start=2025-11-28T10:00:00Z end=2025-11-28T10:10:00Z step=60s ``` ##### レスポンス（200 OK） ```json { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "__name__": "sensor_temperature", "device_id": "sensor_1" }, "values": [ [ 1764324060.0, "0.0016666730244954428" ], [ 1764324120.0, "0.0016666730244954428" ], [ 1764324180.0, "0.0016666412353515624" ], [ 1764324240.0, "0.0016666730244954428" ], [ 1764324300.0, "0.0016666730244954428" ], [ 1764324360.0, "0.0016666730244954428" ], [ 1764324420.0, "0.0016666730244954428" ], [ 1764324480.0, "0.0016666412353515624" ], [ 1764324540.0, "0.0016666730244954428" ], [ 1764324600.0, "0.0016666730244954428" ] ] } ] } } ``` ### GreptimeDB JSON形式のPromQL API EMQX TablesはPromQLを実行しつつ、SQL APIと同様のデータフレームJSON形式で結果を返すAPIも公開しています。 #### エンドポイント ``` GET /v1/promql ``` #### 必須ヘッダー | ヘッダー名 | 説明 | | -------------------- | ------------------------------------------------------------ | | **Authorization** | SQL APIと同様：`Authorization: Basic ` | #### クエリパラメータ | パラメータ | 説明 | | ---------- | -------------------------------------------- | | `db` | データベース名（デフォルトは`public`） | | `query` | PromQL式 | | `start` | 開始時刻（`rfc3339`または`unix_timestamp`） | | `end` | 終了時刻（`rfc3339`または`unix_timestamp`） | | `step` | 解像度ステップ。期間形式または浮動小数点秒数をサポート | | `format` | 任意の出力形式（SQL APIの形式と同様） | #### 対応するタイムスタンプ形式 有効な`start`/`end`値の例： **RFC3339** - `2015-07-01T20:11:00Z`（秒単位の解像度がデフォルト） - `2015-07-01T20:11:00.781Z`（ミリ秒単位の解像度） - `2015-07-02T04:11:00+08:00`（タイムゾーンオフセット付き） **Unixタイムスタンプ** - `1435781460`（秒単位の解像度がデフォルト） - `1435781460.781`（ミリ秒単位の解像度） **期間形式** - `1h`（1時間） - `5d1m`（5日と1分） - `2`（2秒） - `2s`（同じく2秒） #### 例：`irate()`クエリ（GreptimeDB JSON形式） 3分の計算ウィンドウと60秒ステップで温度の増加率をクエリします。 ##### リクエスト ``` GET https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/promql?query=irate(sensor_temperature[3m])&start=2025-11-28T10:00:00Z&end=2025-11-28T10:10:00Z&step=60s Authorization: Basic azgxYTU4ODhxMmFhMTA3NzpwMTFjYjNlMjgyYTc3YWYx ``` ##### レスポンス（200 OK） ```json { "output": [ { "records": { "schema": { "column_schemas": [ { "name": "ts", "data_type": "TimestampMillisecond" }, { "name": "prom_irate(ts_range,temperature)", "data_type": "Float64" }, { "name": "device_id", "data_type": "String" } ] }, "rows": [ [ 1764324060000, 0.0016666730244954428, "sensor_1" ], [ 1764324120000, 0.0016666730244954428, "sensor_1" ], [ 1764324180000, 0.0016666412353515624, "sensor_1" ], [ 1764324240000, 0.0016666730244954428, "sensor_1" ], [ 1764324300000, 0.0016666730244954428, "sensor_1" ], [ 1764324360000, 0.0016666730244954428, "sensor_1" ], [ 1764324420000, 0.0016666730244954428, "sensor_1" ], [ 1764324480000, 0.0016666412353515624, "sensor_1" ], [ 1764324540000, 0.0016666730244954428, "sensor_1" ], [ 1764324600000, 0.0016666730244954428, "sensor_1" ] ], "total_rows": 10, "metrics": { "greptime_cloud_rcu": 2 } } } ], "execution_time_ms": 5 } ``` ## HTTP経由のInfluxDB Line Protocol EMQX TablesはInfluxDBの書き込みAPIと互換性のあるInfluxDB Line Protocolを使った時系列データの取り込みをサポートしています。 ### エンドポイント ``` POST /v1/influxdb/api/v2/write ``` ### クエリパラメータ | パラメータ | 説明 | デフォルト | | ------------ | ------------------------------------ | ---------- | | `db` | 対象データベース | `public` | | `precision` | タイムスタンプの精度（`ns`, `us`, `ms`, `s`） | `ns` | ### 必須ヘッダー #### 認証 SQLおよびPromQL APIとは異なり、InfluxDB Line Protocol APIは以下の形式の認証を使用します： ```sql Authorization: token ``` 例として、ユーザー名が`k81a5888q2aa1077`、パスワードが`p11cb3e282a77af1`の場合、ヘッダーは以下のようになります： ``` Authorization: token k81a5888q2aa1077:p11cb3e282a77af1 ``` ### リクエストボディ InfluxDB Line Protocol仕様に準拠した生の文字列を送信します。 例： ``` sensor_temperature_humidity,device_id="sensor001" temperature=42.0,humidity=42.0 1764295258644 ``` ### レスポンス | ステータス | 意味 | | -------------------- | ---------------- | | **204 No Content** | 書き込み成功 | レスポンスボディは返されません。 ### 例 InfluxDB Line Protocolを使って単一のデータポイントを書き込む例です。 #### リクエスト ``` POST https://k81a5888.ala.us-east-1.aws.emqxtables.com/v1/influxdb/api/v2/write?precision=ms Authorization: token k81a5888q2aa1077:p11cb3e282a77af1 sensor_temperature_humidity,device_id="sensor001" temperature=42.0,humidity=42.0 1764295258644 ``` #### レスポンス ``` 204 No Content ```