Time Series Database:HTTP API

このトピックでは、TSDB for InfluxDB® インスタンスによって提供される HTTP API エンドポイントについて説明します。 この例では、インスタンスが 3242 ポートで実行されており、HTTPS が有効になっていることを前提としています。

TSDB for InfluxDB® HTTP API エンドポイント

/ping HTTP エンドポイント

/ping エンドポイントは、GET および HEAD HTTP リクエストの両方を受け入れます。 /ping を使用して、TSDB for InfluxDB® のバージョンとインスタンスのステータスを確認します。

定義

GET https://<Domain name>:3242/ping?u=<Username>&p=<Password>

HEAD https://<Domain name>:3242/ping?u=<Username>&p=<Password>

verbose オプション

デフォルトでは、/ping エンドポイントは HTTP 204 ステータスコードを返して、サーバーが実行されていることをクライアントに通知します。 verbose のデフォルト値は false です。 verbose が true に設定されている場合 (/ping?verbose=true)、HTTP 200 ステータスコードが返されます。

例

/ping エンドポイントを使用して、TSDB for InfluxDB® インスタンスのバージョンを表示できます。 x-Influxdb-Version ヘッダーフィールドにバージョンが表示されます。

~ curl -sl -I https://<Domain name>:3242/ping?u=<Username>&p=<Password>

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
X-Influxdb-Build: OSS
X-Influxdb-Version: v1.7.x
X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
Date: Tue, 05 Nov 2018 16:08:32 GMT

ステータスコードとレスポンス

レスポンスの本文は空です。

/query HTTP エンドポイント

/query エンドポイントは、GET および POST HTTP リクエストを受け入れます。 このエンドポイントを使用して、データをクエリし、データベース、RP、およびユーザーを管理します。

定義

GET https://<Domain name>:3242/query?u=<Username>&p=<Password>

POST https://<Domain name>:3242/query?u=<Username>&p=<Password>

動詞の使用方法

* 唯一の例外は、POST リクエストを必要とする INTO 句を含む SELECT クエリステートメントです。

例

SELECT ステートメントを実行してデータをクエリする

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

mymeas メジャーメントには 2 つのポイントがあります。 1 つ目のポイントでは、タイムスタンプは 2017-03-01T00:16:18Z、myfield フィールドキーの値は 33.1、mytag1 タグキーと mytag2 タグキーには値がありません。 2 つ目のポイントでは、タイムスタンプは 2017-03-01T00:17:18Z、myfield フィールドキーの値は 12.4、mytag1 タグキーの値は 12、mytag2 タグキーの値は 14 です。

TSDB for InfluxDB® コマンドラインインターフェイス (CLI) での同じクエリは、次の表を返します。

name: mymeas
time                  myfield  mytag1  mytag2
----                  -------  ------  ------
2017-03-01T00:16:18Z  33.1
2017-03-01T00:17:18Z  12.4     12      14

INTO 句を含む SELECT ステートメントを実行してデータをクエリする

$ curl -XPOST 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

SELECT ステートメントで INTO 句を含めてデータをクエリする場合、POST リクエストが必要です。

レスポンスは、TSDB for InfluxDB® が newmeas メジャーメントに 2 つのポイントを書き込んだことを示しています。 システムは、null タイムスタンプとして epoch 0 (1970-01-01T00:00:00Z) を使用します。

文字列クエリパラメーター

* chunked パラメーターが使用されていない場合、TSDB for InfluxDB® はリクエストに対して返される行を切り詰めません。

例

SELECT ステートメントを使用してデータをクエリし、整形された JSON データを返す

$ curl -G 'https://<Domain name>:3242/query?db=mydb&pretty=true&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "mymeas",
                    "columns": [
                        "time",
                        "myfield",
                        "mytag1",
                        "mytag2"
                    ],
                    "values": [
                        [
                            "2017-03-01T00:16:18Z",
                            33.1,
                            null,
                            null
                        ],
                        [
                            "2017-03-01T00:17:18Z",
                            12.4,
                            "12",
                            "14"
                        ]
                    ]
                }
            ]
        }
    ]
}

SELECT ステートメントを使用してデータをクエリし、ナノ秒以外の精度のエポックタイムスタンプを返す。

$ curl -G 'https://<Domain name>:3242/query?db=mydb&epoch=s&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

リクエストボディ

--data-urlencode "q=<InfluxQL query>"

すべてのクエリは URL エンコードされ、InfluxQL 構文に従う必要があります。 このページのすべての例には、curl コマンドに --data-urlencode パラメーターが含まれています。``

オプション

複数のクエリを送信する

セミコロン (;) を使用して複数のクエリを区切ります。

ファイル内のクエリを送信する

マルチパート POST リクエストを使用して、ファイル内のクエリを送信できます。 ファイル内のクエリはセミコロン (;) で区切る必要があります。

構文:

curl -F "q=@<path_to_file>" -F "async=true" https://<Domain name>:3242/query?u=<Username>&p=<Password>

CSV 形式でクエリ結果をリクエストする

構文:

curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?u=<Username>&p=<Password>' [...]

リクエストに -H Accept: application/csv が含まれている場合、システムは RFC 3339 タイムスタンプではなくエポックタイムスタンプを返します。

パラメーターをバインドする

HTTP API を使用すると、WHERE 句で指定されたフィールド値またはタグ値にパラメーターをバインドできます。 クエリでプレースホルダーとして $<placeholder_key> 構文を使用し、リクエストボディでプレースホルダーキーからプレースホルダー値へのマップを URL エンコードします。

クエリ構文:

--data-urlencode 'q= SELECT [...] WHERE [ <field_key> | <tag_key> ] = $<placeholder_key>'

マップ構文:

--data-urlencode 'params={"<placeholder_key>":[ <placeholder_float_field_value> | <placeholder_integer_field_value> | "<placeholder_string_field_value>" | <placeholder_boolean_field_value> | "<placeholder_tag_value>" ]}'

コンマ (,) を使用して複数のプレースホルダーキーと値のペアを区切ります。

例

複数のクエリを送信する

$ curl -G 'https://<Domain name>:3242/query?db=mydb&epoch=s&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]},{"statement_id":1,"series":[{"name":"mymeas","columns":["time","mean"],"values":[[0,22.75]]}]}]}

リクエストには、SELECT * FROM "mymeas" と SELECT mean("myfield") FROM "mymeas" の 2 つのクエリが含まれています。 出力は、システムが返された各クエリに statement_id ステートメント識別子を割り当てることを示しています。 1 つ目のクエリの結果では、statement_id の値は 0 です。 2 つ目のクエリの結果では、statement_id の値は 1 です。

CSV 形式でクエリ結果をリクエストする

$ curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

name,tags,time,myfield,mytag1,mytag2
mymeas,,1488327378000000000,33.1,mytag1,mytag2
mymeas,,1488327438000000000,12.4,12,14

1 つ目のポイントには、mytag1 タグキーと mytag2 タグキーのタグ値がありません。

ファイル内のクエリを送信する

$ curl -F "q=@queries.txt" -F "async=true" 'https://<Domain name>:3242/query?u=<Username>&p=<Password>'

queries.txt ファイル内のクエリの例を次に示します。

SELECT * FROM "mymeas";
SELECT mean("myfield") FROM "mymeas";

WHERE 句のパラメーターを指定されたタグ値にバインドする

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value' --data-urlencode 'params={"tag_value":"12"}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

リクエストは $tag_value を 12 にマップします。 TSDB for InfluxDB® はタグ値を文字列として格納します。 したがって、リクエスト内のタグ値は二重引用符 (“) で囲む必要があります。

WHERE 句のパラメーターを数値フィールド値にバインドする

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "myfield" > $field_value' --data-urlencode 'params={"field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null]]}]}]}

リクエストは $field_value を 30 にマップします。 myfield は数値フィールド値を格納するため、値 30 を二重引用符 (“) で囲む必要はありません。

WHERE 句の 2 つのパラメーターを、それぞれ指定されたタグ値と数値フィールド値にバインドする

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value AND  "myfield" < $field_value' --data-urlencode 'params={"tag_value":"12","field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

リクエストは $tag_value を 12 に、$field_value を 30 にマップします。

ステータスコードとレスポンス

レスポンスは JSON 形式で返されます。 pretty=true を含めて、整形された JSON 出力を有効にすることができます。

概要

例

データを返すリクエスト

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:22:54 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

エラーを返すリクエスト

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb1&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:23:48 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

誤った形式のクエリ

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:24:25 GMT
Content-Length: 76

{"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

無効な認証資格情報を使用するクエリ

$ curl -i  -XPOST 'https://<Domain name>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:11:26 GMT
Content-Length: 33

{"error":"authorization failed"}

/write HTTP エンドポイント

/write エンドポイントは POST HTTP リクエストを受け入れます。 /write を使用して、作成されたデータベースにデータを書き込みます。

定義

POST https://<Domain name>:3242/write?u=<Username>&p=<Password>

文字列クエリパラメーター

** 圧縮パフォーマンスを大幅に向上させるために、時間を最小粒度まで正確にすることをお勧めします。

例

タイムスタンプが秒単位で正確なポイントを mydb データベースに書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&precision=s&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:33:23 GMT

mydb データベースと myrp RP にポイントを書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&rp=myrp&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:31 GMT

HTTP 認証を使用して mydb データベースにポイントを書き込む

有効な資格情報:

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:56 GMT

無効な資格情報:

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:40:30 GMT
Content-Length: 33

{"error":"authorization failed"}

Basic 認証を使用して mydb データベースにポイントを書き込む

有効な資格情報:

$ curl -i -XPOST -u myusername:mypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:36:40 GMT

無効な資格情報:

$ curl -i -XPOST -u myusername:notmypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

リクエストボディ

--data-binary '<Line Protocol 形式のデータ>'

すべてのデータはバイナリエンコードされ、Line Protocol 形式に従う必要があります。 このページのすべての例には、curl コマンドに --data-binary パラメーターが含まれています。 --data-binary 以外のエンコードモードを使用すると、エラーが発生する可能性があります。 -d、--data-urlencode、および --data-ascii モードでは、改行が削除されたり、予期しない形式が導入されたりする可能性があります。

オプション:

• 改行で区切られたポイントを 1 つのリクエストでデータベースに書き込むことができます。

• ファイルからポイントを書き込みます。 アットマーク (@) を使用してファイルを参照します。 ファイル内のポイントは Line Protocol 形式で編成する必要があります。 すべてのポイントを改行 (\n) で区切ります。 ファイルに復帰が含まれている場合、リクエストは解析に失敗します。

5,000 または 10,000 ポイントのバッチでデータを書き込むことをお勧めします。 各バッチに含まれるポイントの数が少ない場合、より多くの HTTP リクエストを送信する必要があります。 これはパフォーマンスを低下させます。

例

ナノ秒タイムスタンプを使用するポイントを mydb データベースに書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:02:57 GMT

ローカルサーバーのナノ秒タイムスタンプを使用するポイントを mydb データベースに書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:03:44 GMT

改行で区切られた複数のポイントを mydb データベースに書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
mymeas,mytag=2 myfield=34 1463689152000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:04:02 GMT

data.txt ファイルから複数のポイントを mydb データベースに書き込む

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary @data.txt

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:08:11 GMT

data.txt ファイルのデータの例を次に示します。

mymeas,mytag1=1 value=21 1463689680000000000
mymeas,mytag1=1 value=34 1463689690000000000
mymeas,mytag2=8 value=78 1463689700000000000
mymeas,mytag3=9 value=89 1463689710000000000

ステータスコードとレスポンス

一般に、2xx ステータスコードは成功を示し、4xx ステータスコードは TSDB for InfluxDB® がリクエストの解析に失敗したことを示し、5xx ステータスコードはシステムが過負荷状態または著しく機能低下していることを示します。 エラーは JSON 形式で返されます。

概要

例

データの書き込みに成功する

HTTP/1.1 204 No Content

誤ったタイムスタンプを使用するポイントを書き込む

HTTP/1.1 400 Bad Request
[...]
{"error":"unable to parse 'mymeas,mytag=1 myfield=91 abc123': bad timestamp"}

以前に浮動小数点を受け入れたフィールドに整数を書き込む

HTTP/1.1 400 Bad Request
[...]
{"error":"field type conflict: input field \"myfield\" on measurement \"mymeas\" is type int64, already exists as type float"}

無効な認証資格情報を使用してデータを書き込む

HTTP/1.1 401 Unauthorized
[...]
{"error":"authorization failed"}

存在しないデータベースにポイントを書き込む

HTTP/1.1 404 Not Found
[...]
{"error":"database not found: \"mydb1\""}

存在しない RP にポイントを書き込む

HTTP/1.1 500 Internal Server Error
[...]
{"error":"retention policy not found: myrp"}

InfluxDB® は InfluxData によって登録された商標であり、TSDB for InfluxDB® とは提携しておらず、TSDB for InfluxDB® を推奨していません。