如需與 Amazon Timestream for LiveAnalytics 類似的功能，請考慮使用 Amazon Timestream for InfluxDB。它提供簡化的資料擷取和單一位數毫秒查詢回應時間，以進行即時分析。[在這裡](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/)。做為schema-on-write資料庫，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
```
這會在「主」資料表中建立一個點，其中包含：
+ 標籤： room="Living Room"
+ 欄位： temp=21.1 （浮點數）、 hum=35.9 （浮點數）、 co=0 （整數）
+ 時間戳記： 1735545600 (Unix 秒）
## API 端點概觀
InfluxDB 3 支援三個主要寫入端點：
1. **原生 v3 API** (`/api/v3/write_lp`)：新實作的建議端點。
1. **v2 相容性 API** (`/api/v2/write`)：用於遷移 InfluxDB v2.x 工作負載。
1. **v1 相容性 API** (`/write`)：用於遷移 InfluxDB v1.x 工作負載。
### 使用原生 v3 寫入 API
`/api/v3/write_lp` 端點是用於寫入線路通訊協定資料的原生 InfluxDB 3 API。
請求格式：
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
查詢參數：
| **Parameter (參數)** | **描述** | **預設** |
| --- | --- | --- |
| db | 資料庫名稱 （必要） | - |
| precision | 時間戳記精確度 (ns、us、ms、s) | 自動偵測 |
| 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 (Write-Ahead Log)，再確認。
+ 提供耐久性保證。
+ 由於 WAL 持久性等待，延遲更高。
+ 建議用於耐久性至關重要的關鍵資料。
快速模式 (`no_sync`=true)
+ 立即確認，無需等待 WAL 持久性。
+ 可能的最低寫入延遲。
+ 如果系統在 WAL 寫入完成之前當機，資料遺失的風險。
+ 非常適合速度優先於絕對耐用性的高輸送量案例。
### 部分寫入處理
參數 `accept_partial` 控制寫入批次包含錯誤時的行為：
當 `accept_partial`為 時 `true`（預設）：
+ 成功寫入有效行。
+ 無效行會遭到拒絕。
+ 傳回 400 狀態，其中包含失敗行的詳細資訊。
+ 適用於可接受某些失敗的大型批次操作。
當 `accept_partial` 為 `false`：
+ 如果任何行失敗，整個批次都會遭到拒絕。
+ 不會寫入任何資料。
+ 傳回包含錯誤詳細資訊的 400 狀態。
+ 確保all-or-nothing寫入語意。
### 相容性 APIs
相容性 APIs可將現有的 InfluxDB v1 或 v2 工作負載無縫遷移至 InfluxDB 3。這些端點可與現有的 InfluxDB 用戶端程式庫、Telegraf 和第三方整合搭配使用。
**重要差異：**
+ 資料表中的標籤 （測量） 在建立後是不可變的。
+ 標籤和欄位在資料表中不能具有相同的名稱。
+ 寫入時強制執行結構描述驗證。
#### InfluxDB v2 相容性
端點為 v2 `/api/v2/write` 用戶端提供回溯相容性：
```
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 參數：
| **Parameter (參數)** | **位置** | **Description** |
| --- | --- | --- |
| bucket \* | 查詢字串 | 映射至資料庫名稱 |
| precision | 查詢字串 | 時間戳記精確度 (ns、us、ms、s、m、h) |
| Authorization | 標頭 | 承載或權杖配置 |
| Content-Encoding | 標頭 | gzip 或身分 |
##### InfluxDB v1 相容性
端點為 v1 `/write` 用戶端提供回溯相容性：
```
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"`)。
+ 查詢參數： `p=TOKEN` 在 URL 中。
+ Bearer/Token 標頭：標準授權標頭。
V1 API 參數：
| **Parameter (參數)** | **位置** | **Description** |
| --- | --- | --- |
| db \* | 查詢字串 | 資料庫名稱 |
| precision | 查詢字串 | 時間戳記精確度 |
| p | 查詢字串 | 查詢身分驗證的字符 |
| u | 查詢字串 | 使用者名稱 （已忽略） |
| Authorization | 標頭 | 支援的多個方案 |
| Content-Encoding | 標頭 | gzip 或身分 |
## 用戶端程式庫和整合
### 官方 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 行或每個請求 10MB。
+ 針對大型承載使用壓縮 (gzip)。
+ 依索引鍵依詞典順序排序標籤，以獲得更好的效能。
+ 時間戳記精確度
+ 使用符合您需求的最粗精確度。
+ 明確指定精確度以避免模棱兩可的情況。
+ 在整個應用程式中維持一致的精確度。
+ 錯誤處理
+ 實作暫時性失敗的重試邏輯。
+ 使用 accept\_partial=true 進行彈性批次操作。
+ 透過 CloudWatch 指標監控寫入錯誤。
+ 效能調校
+ 針對高輸送量案例 使用 no\_sync=true。
+ 將寫入分散到多個連線。
+ 使用寫入器/讀取器端點進行所有寫入操作。
+ 結構描述考量
+ 標籤在建立後是不可變的。
+ 欄位和標籤無法共用相同的 nam.e
+ 以查詢模式為考量的設計結構描述。
+ 控制標籤基數。
與先前版本的重要差異：
+ 不可變標籤：在資料表中建立標籤後，就無法變更其類型
+ 沒有標籤/欄位名稱衝突：標籤和欄位在資料表中不能有相同的名稱
+ Schema-on-write：InfluxDB 3 驗證寫入時的資料類型
+ 自動建立資料表：資料表會在第一次寫入時自動建立
+ 嚴格類型檢查：欄位類型在所有寫入之間必須保持一致
透過利用適當的寫入 API 並遵循這些最佳實務，您可以有效率地將時間序列資料擷取至 Timestream for InfluxDB 3 執行個體，同時維持高效能和資料完整性。