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 つのフィールドが含まれます。
| フィールド | 型 | 説明 | 例 |
|---|---|---|---|
metric | String | 時系列の名前 | sys.cpu |
timestamp | Long | ミリ秒単位の UNIX タイムスタンプ | 1711555200000 |
value | Double | 測定値 | 32.4 |
tags | Map<String, String> | データソースを識別するキーと値のペア | 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 アドレスとポートに置き換えてください。
仕組み
buildData()メソッドは、3,600 個のDataPointオブジェクトのリストを作成し、JSON 配列にシリアル化します。putDemo()メソッドは、JSON 配列を HTTP POST として/api/put?sync_timeout=60000に送信します。sync_timeoutパラメーター(ミリ秒単位)により、サーバーは書き込みが完了するまで最大 60 秒間待機してから応答を返します。200または204の状態コードは、すべてのデータポイントが正常に保存されたことを意味します。400の状態コードは、1 つ以上のデータポイントが失敗したことを示します。どのポイントが拒否されたか、およびその理由を記述したエラーメッセージについては、レスポンスボディをご確認ください。
注意事項
バッチサイズ:この例では、1 回のリクエストで 3,600 個のデータポイントを書き込みます。本番ワークロードやサーバー容量に基づいて、バッチサイズを調整してください。
タイムスタンプ:ミリ秒精度の UNIX タイムスタンプを使用します。この例では、基準として
System.currentTimeMillis()を使用し、各ポイントごとに 1,000 ms ずつ増分しています。接続の再利用:繰り返し書き込む場合は、リクエストごとに新しい
CloseableHttpClientインスタンスを作成するのではなく、既存のインスタンスを再利用してください。エラー処理:部分的な失敗を検出し、失敗したデータポイントをリトライまたはログに記録するため、2xx 以外の状態コードに対する処理を追加してください。