すべてのプロダクト
Search

このプロダクト

    Time Series Database:HTTP API を使用したデータの書き込み

    ドキュメントセンター

    Time Series Database:HTTP API を使用したデータの書き込み

    最終更新日:Jan 14, 2025

    CLI やクライアントライブラリなど、複数の方法を使用して、Time Series Database (TSDB) for InfluxDB® にデータを書き込むことができます。このトピックでは、組み込みの HTTP API を使用してデータを書き込む方法について説明します。

    説明

    このトピックで提供されている例では、curl ツールを使用しています。 curl ツールは、URL を使用してデータを送信する CLI です。

    HTTP API は、TSDB for InfluxDB® にデータを書き込むために使用される主要な方法です。 HTTP API を使用してデータを書き込むには、/write エンドポイントに POST リクエストを送信します。データを書き込む前に、TSDB for InfluxDB® インスタンスにデータベースを作成します。このトピックでは、mydb という名前のデータベースが作成され、使用されます。次のセクションでは、HTTP API を使用して mydb にデータを書き込む方法について説明します。

    単一のデータポイントの書き込み

    次の例は、mydb データベースに単一のデータポイントを書き込む方法を示しています。データポイントには、cpu_load_short メジャーメントと 2 つのタグが含まれています。タグキーは host と region です。対応するタグ値は server01 と us-west です。フィールドキーは value で、フィールド値は 0.64 です。タイムスタンプは 1434055562000000000 です。

    curl -i -XPOST 'https://<ドメイン名>:3242/write?db=mydb&u=<アカウント名>&p=<パスワード>' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

    • <ドメイン名> は、TSDB for InfluxDB® インスタンスのドメイン名を指定します。

    • <アカウント名> と <パスワード> は、TSDB for InfluxDB® インスタンスに作成したアカウントのユーザー名とパスワードを指定します。

    • デフォルトでは、TSDB for InfluxDB® はポート 3242 を使用します。

    • データポイントを書き込むときは、db パラメーターを使用して既存のデータベースを指定する必要があります。 rp パラメーターを使用してデータ保持ポリシーを設定しない場合、データポイントは db パラメーターで指定されたデータベースのデフォルトのデータ保持ポリシーに基づいて書き込まれます。

    リクエストパラメーターの完全なリストについては、「HTTP API リファレンス」をご参照ください。

    POST リクエストの本文には、行プロトコル形式で保存する時系列データポイントが含まれています。本文は、メジャーメント、タグ、フィールド、およびタイムスタンプで構成されます。 TSDB for InfluxDB® の時系列データポイントには、メジャーメントを指定する必要があります。タグはオプションですが、ほとんどの時系列データポイントには、データのソースを識別するために使用されるタグが含まれています。これにより、クエリが簡単かつ効率的になります。タグキーとタグ値は文字列である必要があります。フィールドキーは必須であり、文字列である必要があります。フィールド値のデフォルトのデータ型は FLOAT です。タイムスタンプは、行の最後に UNIX 時間形式で指定されます。タイムスタンプの値はナノ秒単位で、1970 年 1 月 1 日木曜日 00:00:00 UTC から経過した時間を示します。タイムスタンプはオプションです。タイムスタンプを指定しない場合、TSDB for InfluxDB® は、インスタンスがデプロイされている場所の UNIX タイムスタンプをデータポイントのタイムスタンプとして使用します。 TSDB for InfluxDB® のタイムスタンプは、UTC+0 タイムゾーンを使用します。

    複数のデータポイントの書き込み

    1 つの POST リクエストで複数のデータポイントを指定し、改行で区切ることができます。このようにして、複数のデータポイントが複数の時系列に同時に送信されます。これにより、データベースのパフォーマンスが向上する可能性があります。

    次の例は、1 つの POST リクエストを使用して mydb データベースに 3 つのデータポイントを書き込む方法を示しています。

    • 最初のデータポイントは、cpu_load_short メジャーメントと host=server0 タグを持つ時系列に属しています。このデータポイントは、インスタンスが存在する場所のタイムスタンプを使用します。

    • 2 番目のデータポイントは、cpu_load_short メジャーメントと host=server02,region=us-west タグセットを持つ時系列に属しています。タイムスタンプは 142256854370290025 です。

    • 3 番目のデータポイントは、cpu_load_short メジャーメントと direction=in,host=server01,region=us-west タグセットを持つ時系列に属しています。タイムスタンプは、2 番目のデータポイントと同じです。

    curl -i -XPOST 'https://<ドメイン名>:3242/write?db=mydb&u=<アカウント名>&p=<パスワード>' --data-binary 'cpu_load_short,host=server02 value=0.67
cpu_load_short,host=server02,region=us-west value=0.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=2.0 1422568543702900257'

    ファイルからのデータポイントの書き込み

    curl に @filename を渡すことにより、ファイルから TSDB for InfluxDB® にデータポイントを書き込むことができます。ファイル内のデータは、行プロトコル構文に従う必要があります。

    次のコードは、行プロトコル構文に準拠したファイルの例を示しています。ファイル名は cpu_data.txt です。

    cpu_load_short,host=server02 value=0.67
cpu_load_short,host=server02,region=us-west value=0.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=2.0 1422568543702900257

    次のコマンドを実行して、cpu_data.txt ファイルのデータを mydb データベースに書き込みます。

    curl -i -XPOST 'https://<ドメイン名>:3242/write?db=mydb&u=<アカウント名>&p=<パスワード>' --data-binary @cpu_data.txt
    説明

    デフォルトでは、HTTP リクエストは 5 秒後にタイムアウトします。ファイルに多数のデータポイントが含まれている場合、リクエストがタイムアウトした後に TSDB for InfluxDB® が残りのデータポイントの書き込みに失敗する可能性があります。この場合、ファイルを分割することをお勧めします。たとえば、ファイルに 5,000 を超えるデータポイントが含まれている場合は、ファイルを複数のファイルに分割し、ファイルデータをバッチで TSDB for InfluxDB® に書き込みます。

    スキーマレス設計

    TSDB for InfluxDB® は、スキーマレスデータベースを提供します。ビジネス要件に基づいて、新しいメジャーメント、タグ、およびフィールドを追加できます。

    重要

    保存されているデータポイントとは異なるデータ型を使用するデータポイントを書き込もうとすると、TSDB for InfluxDB® はこれらのデータポイントを拒否します。たとえば、整数が書き込まれているフィールドに文字列を書き込むことはできません。

    REST の使用上の注意

    TSDB for InfluxDB® は、広く使用されている HTTP プロトコルを使用してデータを送信します。

    最新の Web API は、Representational State Transfer (REST) アーキテクチャに基づいています。これは、REST が次の一般的な問題を解決するためです。エンドポイントの数が増加すると、組織化システムの必要性が差し迫ってきます。 REST は、多数のエンドポイントを整理するための業界で認められた標準です。すべての参加者が何を期待するかを知っているため、業界で一貫した標準を使用することは、API の開発者と利用者にメリットをもたらします。

    ただし、REST は単なる規則です。 TSDB for InfluxDB® は、3 つの API エンドポイントのみを提供し、HTTP を使用して InfluxQL ステートメントを転送する、シンプルで使いやすいシステムです。 TSDB for InfluxDB® の API は、RESTful 標準に完全には準拠していません。

    HTTP レスポンスの概要

    • 2xx: 書き込みリクエストに対して HTTP 204 No Content メッセージが返された場合、データは TSDB for InfluxDB® に書き込まれます。

    • 4xx: TSDB for InfluxDB® がリクエストを解析できません。

    • 5xx: システムが過負荷になっているか、深刻な損傷を受けています。

    次の部分は、サンプルエラーレスポンスを提供します。

    • ブール値が格納されているフィールドに浮動小数点数を書き込みます。

    curl -i -XPOST 'https://<ドメイン名>:3242/write?db=<データベース名>&u=<アカウント名>&p=<パスワード>' --data-binary 'tobeornottobe booleanonly=true'

curl -i -XPOST 'https://<ドメイン名>:3242/write?db=<データベース名>&u=<アカウント名>&p=<パスワード>' --data-binary 'tobeornottobe booleanonly=5'

    システムは次のレスポンスを返します。

    HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 01 Mar 2017 19:38:01 GMT
Content-Length: 150

{"error":"field type conflict: input field \"booleanonly\" on measurement \"tobeornottobe\" is type float, already exists as type boolean dropped=1"}

    • 存在しないデータベースにデータを書き込みます。

    curl -i -XPOST 'https://<ドメイン名>:3242/write?db=atlantis&u=<アカウント名>&p=<パスワード>' --data-binary 'liters value=10'

    システムは次のレスポンスを返します。

    HTTP/1.1 404 Not Found
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 01 Mar 2017 19:38:35 GMT
Content-Length: 45

{"error":"database not found: \"atlantis\""}

    次のステップ

    TSDB for InfluxDB® の組み込み HTTP API を使用してデータベースにデータが書き込まれた後、データをクエリできます。詳細については、「HTTP API を使用したデータのクエリ」をご参照ください。 HTTP API を使用してデータを書き込む方法の詳細については、「HTTP API リファレンス」をご参照ください。

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