EMQX Cloud

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ
お問い合わせ

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
<BASE_URL>/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 <Base64(username:password)>
  • 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/<label_name>/values

すべてのエンドポイントはGETおよびPOSTをサポートします。

必須ヘッダー ​

ヘッダー名説明
AuthorizationSQL APIと同様：Authorization: Basic <Base64(username:password)>
Content-TypePOSTリクエスト時のみ必須：application/x-www-form-urlencoded

クエリパラメータ ​

パラメータ説明デフォルト
dbデータベース名public

その他のクエリパラメータはPrometheus仕様に準拠します：

  • GETリクエストの場合：URLエンコードされたクエリパラメータを使用します。詳細はPrometheusドキュメントを参照してください。
  • 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

必須ヘッダー ​

ヘッダー名説明
AuthorizationSQL APIと同様：Authorization: Basic <Base64(username:password)>

クエリパラメータ ​

パラメータ説明
dbデータベース名（デフォルトはpublic）
queryPromQL式
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 <username:password>

例として、ユーザー名が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