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)>
  • User Managementでusernameとpasswordを作成・管理します。
  • これらの認証情報はすべてのAPIアクセスに必須です。

Base64エンコード文字列の作成方法：

  1. usernameとpasswordをコロンで連結します：

    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のコンテンツタイプで送信します。このコンテンツタイプはリクエストボディが単純なキー・バリュー形式でエンコードされていることを意味します：

  • キー：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はHTTP APIを通じてPrometheus Query Language（PromQL）を用いた時系列データのクエリをサポートしています。

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>

例：usernameがk81a5888q2aa1077、passwordが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