すべてのプロダクト
Search
ドキュメントセンター

Time Series Database:コード例

最終更新日:Mar 28, 2026

HTTP API を使用して、時系列データを Time Series Database (TSDB) に書き込みます。このページでは、迅速な検証用の最小限の curl の例と、データポイントを構築して /api/put エンドポイントに送信する完全な Java の例を提供します。

前提条件

作業を開始する前に、以下の環境が整っていることを確認してください。

  • IP アドレスとポートが既知の実行中の TSDB インスタンス

  • Java 開発環境

  • 依存関係管理のための Maven

curl で接続を確認する

Java プロジェクトをセットアップする前に、次の curl コマンドを実行して、ご利用の TSDB インスタンスに到達可能であり、データを受け入れられることを確認します。

curl -i -X POST "http://<TSDB_IP>:<TSDB_PORT>/api/put" \
  -H "Content-Type: application/json" \
  -d '[{"metric":"sys.cpu","timestamp":1711555200000,"value":32.4,"tags":{"host":"host1"}}]'

<TSDB_IP> および <TSDB_PORT> は、ご利用のインスタンスの IP アドレスとポートに置き換えてください。

200 または 204 の応答は、データポイントが正常に保存されたことを意味します。400 の応答は、リクエストの形式が不正であることを示します。詳細については、レスポンスボディをご確認ください。

依存関係の追加

以下の依存関係を pom.xml ファイルに追加します。

<!-- https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient -->
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.alibaba/fastjson -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.82</version>
</dependency>

この例では、HTTP POST リクエストを送信するために Apache HTTP Client を、データポイントを JSON にシリアル化するために FastJSON を使用しています。

データモデル

TSDB に書き込まれる各データポイントには、以下の 4 つのフィールドが含まれます。

フィールド型説明例
metricString時系列の名前sys.cpu
timestampLongミリ秒単位の UNIX タイムスタンプ1711555200000
valueDouble測定値32.4
tagsMap&lt;String, String&gt;データソースを識別するキーと値のペアhost=host1、appName=test1

タグは必須であり、少なくとも 1 組のキーと値のペアを含める必要があります。クエリ時にデータをフィルターやグループ化するために使用されます。

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

以下の例では、3,600 個のデータポイントを 1 回の HTTP POST リクエストで /api/put エンドポイントに書き込みます。すべてのデータポイントは同じメトリック (sys.cpu) とタグを共有し、タイムスタンプは 1 秒間隔で設定されています。

package org.hitsdb.client;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.junit.Test;

import com.alibaba.fastjson.JSON;

public class HttpWrite {
  private final static String HITSDB_IP = "192.168.11.17";  //インスタンスのアドレス
  private final static int HITSDB_PORT = 8242; //インスタンスのポート
  private final static int SYNC_TIMEOUT_MS = 60 * 1000;
  private Long startTime = System.currentTimeMillis();

  static String putUrl = "http://" + HITSDB_IP + ":" + HITSDB_PORT +
                  "/api/put?sync_timeout=" + SYNC_TIMEOUT_MS;
  static String queryUrl = "http://" + HITSDB_IP + ":" + HITSDB_PORT +
                    "/api/query";


  static class DataPoint {
    public String metric;
    public Long timestamp;
    public Double value;
    public Map<String, String> tags;
  }

  String buildData() {
    // 書き込み用データエンティティを構築
    List<DataPoint> dataPoints = new ArrayList<DataPoint>();
    for (int i = 0; i < 3600; ++i) {
      DataPoint dataPoint = new DataPoint();
      dataPoint.metric = "sys.cpu";
      dataPoint.timestamp = startTime + i * 1000;
      dataPoint.value = 32.4;
      dataPoint.tags = new HashMap<String, String>();
      dataPoint.tags.put("host", "host1");
      dataPoint.tags.put("appName", "test1");
      dataPoints.add(dataPoint);
    }
    return JSON.toJSONString(dataPoints);
  }

  @Test
  public void putDemo() throws ClientProtocolException, IOException {
    CloseableHttpClient httpClient = HttpClients.createDefault();
    HttpPost httpPost = new HttpPost(putUrl);
    StringEntity eStringEntity = new StringEntity(buildData(), "utf-8");
    eStringEntity.setContentType("application/json");
    httpPost.setEntity(eStringEntity);
    HttpResponse response = httpClient.execute(httpPost);
    int statusCode = response.getStatusLine().getStatusCode();
    if (statusCode == 200 || statusCode == 204) {
      System.out.println("write OK");
    }
    httpClient.close();
  }
}

192.168.11.17 および 8242 は、ご利用のインスタンスの IP アドレスとポートに置き換えてください。

仕組み

  1. buildData() メソッドは、3,600 個の DataPoint オブジェクトのリストを作成し、JSON 配列にシリアル化します。

  2. putDemo() メソッドは、JSON 配列を HTTP POST として /api/put?sync_timeout=60000 に送信します。

  3. sync_timeout パラメーター(ミリ秒単位)により、サーバーは書き込みが完了するまで最大 60 秒間待機してから応答を返します。

  4. 200 または 204 の状態コードは、すべてのデータポイントが正常に保存されたことを意味します。400 の状態コードは、1 つ以上のデータポイントが失敗したことを示します。どのポイントが拒否されたか、およびその理由を記述したエラーメッセージについては、レスポンスボディをご確認ください。

注意事項

  • バッチサイズ:この例では、1 回のリクエストで 3,600 個のデータポイントを書き込みます。本番ワークロードやサーバー容量に基づいて、バッチサイズを調整してください。

  • タイムスタンプ:ミリ秒精度の UNIX タイムスタンプを使用します。この例では、基準として System.currentTimeMillis() を使用し、各ポイントごとに 1,000 ms ずつ増分しています。

  • 接続の再利用:繰り返し書き込む場合は、リクエストごとに新しい CloseableHttpClient インスタンスを作成するのではなく、既存のインスタンスを再利用してください。

  • エラー処理:部分的な失敗を検出し、失敗したデータポイントをリトライまたはログに記録するため、2xx 以外の状態コードに対する処理を追加してください。