Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Timestream for InfluxDB 3 クラスターへのデータの書き込み
Amazon Timestream for InfluxDB 3 は、時系列データを効率的に取り込むための堅牢な機能を提供します。パフォーマンスを最大化し、データの完全性を確保するためには、データを書き込むための適切な方法を理解することが不可欠です。
Timestream for InfluxDB 3 は、時系列データを書き込むための複数の HTTP API エンドポイントを提供し、さまざまな統合方法と既存の InfluxDB ワークロードとの互換性に対する柔軟性を提供します。
## ラインプロトコルの概要
InfluxDB 3 は、高い書き込みスループットを実現できるように設計されており、[ラインプロトコル](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/)と呼ばれる効率的で人間が読める書き込み構文を使用します。スキーマオンライトデータベースとして、InfluxDB はデータの書き込みを開始するときに、手動設定を必要とせずに論理データベース、テーブル、およびスキーマを自動的に作成します。スキーマが作成されると、InfluxDB は新しいデータを受け入れる前に、スキーマに対する将来の書き込みリクエストを検証しつつ、ニーズの変化に応じたスキーマの進化を可能にします。
### ラインプロトコル構造
ラインプロトコルは、次の必須要素で構成されます。
+ **テーブル**: データを保存するテーブルの文字列識別子。
+ (オプション) **タグセット**: メタデータを表すカンマ区切りのキーと値のペア (インデックス付き)。
+ **フィールドセット**: 実際の測定値を表すカンマ区切りのキーと値のペア。
+ (オプション) **タイムスタンプ**: 最高ナノ秒単位の精度のデータポイントに関連付けられた Unix タイムスタンプ。
フィールド値は以下のデータ型を設定できます。
+ 文字列 (引用符で囲む必要があります)
+ 浮動小数点 (23.4 など)
+ 整数 (10i など)
+ 符号なし整数 (10u など)
+ ブール値 (true/false)
ラインプロトコルは次の一般的な構文に従います。
```
myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
```
ラインプロトコルを使用したデータポイントの例:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
```
これにより、以下を含む「home」テーブルにポイントが作成されます。
+ タグ: room="Living Room"
+ フィールド: temp=21.1 (浮動小数点)、hum=35.9 (浮動小数点)、co=0 (整数)
+ タイムスタンプ: 1735545600 (Unix 秒)
## API エンドポイントの概要
InfluxDB 3 は 3 つのプライマリ書き込みエンドポイントをサポートしています。
1. **ネイティブ v3 API** (`/api/v3/write_lp`): 新しい実装に推奨されるエンドポイント。
1. **v2 Compatibility API** (`/api/v2/write`): InfluxDB v2.x ワークロードの移行用。
1. **v1 Compatibility API** (`/write`): InfluxDB v1.x ワークロードの移行用。
### ネイティブ v3 Write API の使用
`/api/v3/write_lp` エンドポイントは、ラインプロトコルデータを書き込むためのネイティブ InfluxDB 3 API です。
リクエストの形式:
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
クエリパラメータ:
| **パラメータ** | **説明** | **デフォルト** |
| --- | --- | --- |
| db | データベース名 (必須) | - |
| precision | タイムスタンプの精度 (ns、us、ms、s) | Auto-detected |
| accept\_partial | エラーに対する部分的な書き込みを受け入れる | true |
| no\_sync | WAL 永続化の前に承認する | false |
####
書き込みリクエストの例:
```
curl -v "https://your-cluster-endpoint:8086/api/v3/write_lp?db=sensors&precision=s" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600"
```
### 書き込みレスポンスモード
標準モード (`no_sync`=false)
+ 確認する前に、データが WAL (先行書き込みログ) に書き込まれるのを待ちます。
+ 耐久性の保証を提供します。
+ WAL 永続性待機によりレイテンシーが増加します。
+ 耐久性が必須の重要なデータに推奨されます。
高速モード (`no_sync`=true)
+ WAL 永続化を待たずにすぐに承認します。
+ 可能な限り低い書き込みレイテンシー。
+ WAL 書き込みが完了する前にシステムがクラッシュすると、データ損失のリスクがあります。
+ 絶対的な耐久性よりも速度が優先される高スループットのシナリオに最適です。
### 部分的な書き込み処理
`accept_partial` パラメータは、書き込みバッチにエラーが含まれている場合の動作を制御します。
`accept_partial` が `true` のとき (デフォルト):
+ 有効な行は正常に書き込まれます。
+ 無効な行は拒否されます。
+ 失敗した行については詳細を含む 400 ステータスを返します。
+ 一部の障害が許容される大規模なバッチオペレーションに役立ちます。
`accept_partial` が `false` のとき:
+ 行が失敗すると、バッチ全体が拒否されます。
+ データは書き込まれません。
+ エラーの詳細を含む 400 ステータスが返されます。
+ all-or-nothing の書き込みセマンティクスを確保します。
### Compatibility API
Compatibility API を使用すると、既存の InfluxDB v1 または v2 ワークロードを InfluxDB 3 にシームレスに移行できます。これらのエンドポイントは、既存の InfluxDB クライアントライブラリ、Telegraf、サードパーティーの統合で機能します。
**重要な相違:**
+ テーブル (メジャーメント) 内のタグは、作成後に変更できません。
+ タグとフィールドは、テーブル内で同じ名前にすることはできません。
+ スキーマの検証は書き込み時に強制されます。
#### InfluxDB v2 の互換性
`/api/v2/write` エンドポイントは v2 クライアントの下位互換性を提供します。
```
curl -i "https://your-cluster-endpoint:8086/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
V2 API パラメータ:
| **パラメータ** | **場所** | **説明** |
| --- | --- | --- |
| bucket \* | クエリ文字列 | データベース名にマッピング |
| precision | クエリ文字列 | タイムスタンプの精度 (ns、us、ms、s、m、h) |
| Authorization | ヘッダー | ベアラーまたはトークンスキーム |
| Content-Encoding | ヘッダー | gzip または ID |
##### InfluxDB v1 の互換性
`/write` エンドポイントは v1 クライアントの下位互換性を提供します。
```
curl -i "https://your-cluster-endpoint:8086/write?db=DATABASE_NAME&precision=s" \
--user "any:DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
V1 認証オプション:
+ 基本認証: パスワードとしてのトークン (`--user "any:TOKEN"`)。
+ クエリパラメータ: URL 内の `p=TOKEN`。
+ ベアラー/トークンヘッダー: 標準認可ヘッダー。
V1 API パラメータ:
| **パラメータ** | **場所** | **説明** |
| --- | --- | --- |
| db \* | クエリ文字列 | [Database name] (データベース名) |
| precision | クエリ文字列 | タイムスタンプの精度 |
| p | クエリ文字列 | クエリ認証のトークン |
| u | クエリ文字列 | ユーザー名 (無視) |
| Authorization | ヘッダー | 複数のスキームのサポート |
| Content-Encoding | ヘッダー | gzip または ID |
## クライアントライブラリと統合
### 公式 InfluxDB 3 クライアントライブラリ
InfluxDB 3 クライアントライブラリは、時系列データを構築および記述するためのネイティブ言語インターフェイスを提供します。
+ **Python**: `influxdb3-python`
+ **Go**: `influxdb3-go`
+ **JavaScript/Node.js**: `influxdb3-js`
+ **Java**: `influxdb3-java`
+ **C\#**: `InfluxDB3.Client`
例: Python クライアント
```
from influxdb3 import InfluxDBClient3
client = InfluxDBClient3(
host="your-cluster-endpoint:8086",
token="YOUR_TOKEN",
database="DATABASE_NAME"
)
# Write using line protocol
client.write("home,room=Living\\ Room temp=21.1,hum=35.9,co=0i")
# Write using Point objects
from influxdb3 import Point
point = Point("home") \
.tag("room", "Living Room") \
.field("temp", 21.1) \
.field("hum", 35.9) \
.field("co", 0)
client.write(point)
```
例: Go クライアント
```
import "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "your-cluster-endpoint:8086",
Token: "YOUR_TOKEN",
Database: "DATABASE_NAME",
})
point := influxdb3.NewPoint("home",
map[string]string{"room": "Living Room"},
map[string]any{
"temp": 24.5,
"hum": 40.5,
"co": 15,
},
time.Now(),
)
err = client.WritePoints(context.Background(), []*influxdb3.Point{point})
```
### レガシークライアントライブラリ
既存の v1 および v2 ワークロードでは、次のように互換性エンドポイントでレガシークライアントライブラリを引き続き使用できます。
例: Node.js v1 クライアント:
```
const Influx = require('influx')
const client = new Influx.InfluxDB({
host: 'your-cluster-endpoint',
port: 8086,
protocol: 'https',
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
```
## データ書き込みのベストプラクティス
データを書き込むときは、次をお勧めします。
+ バッチ最適化
+ 最適なバッチサイズ: リクエストあたり 5,000～10,000 行または 10 MB。
+ 大きなペイロードには圧縮 (gzip) を使用します。
+ パフォーマンスを向上させるために、キーでタグを辞書式順序にソートします。
+ タイムスタンプの精度
+ ニーズに合った最も粗い精度を使用します。
+ あいまいさを避けるために、明示的に精度を指定します。
+ アプリケーション全体で一貫した精度を維持します。
+ エラー処理
+ 一時的な障害に対する再試行ロジックを実装します。
+ 回復力のあるバッチオペレーションには accept\_partial=true を使用します。
+ CloudWatch メトリクスを使用して書き込みエラーをモニタリングします。
+ パフォーマンスチューニング
+ 高スループットのシナリオには no\_sync=true を使用します。
+ 複数の接続に書き込みを分散します。
+ すべての書き込みオペレーションにライター/リーダーエンドポイントを使用します。
+ スキーマに関する考慮事項
+ タグは、一度作成すると変更できません。
+ フィールドとタグは同じ名前を共有できません。
+ クエリパターンを念頭に置いてスキーマを設計します。
+ タグカーディナリティを継続的に制御します。
以前のバージョンとの重要な違い:
+ イミュータブルタグ: テーブルにタグが作成されると、そのタイプを変更することはできません
+ タグ/フィールド名の競合禁止: タグとフィールドをテーブル内で同じ名前にすることはできません
+ スキーマオンライト: InfluxDB 3 が書き込み時にデータ型を検証します
+ 自動テーブル作成: テーブルは最初の書き込み時に自動的に作成されます
+ 厳密な型チェック: フィールド型はすべての書き込みで一貫性を保つ必要があります
適切な書き込み API を活用し、これらのベストプラクティスに従うことで、高いパフォーマンスとデータの完全性を維持しつつ、時系列データを Timestream for InfluxDB 3 インスタンスに効率的に取り込むことができます。