Menulis data ke Timestream Anda untuk cluster InfluxDB 3

Amazon TimeStream untuk InfluxDB 3 menyediakan kemampuan yang kuat untuk menyerap data deret waktu secara efisien. Memahami metode yang tepat untuk menulis data sangat penting untuk memaksimalkan kinerja dan memastikan integritas data.

Timestream untuk InfluxDB 3 menyediakan beberapa titik akhir HTTP API untuk menulis data deret waktu, menawarkan fleksibilitas untuk berbagai metode integrasi dan kompatibilitas dengan beban kerja InfluxDB yang ada.

Ikhtisar protokol baris

InfluxDB 3 dirancang untuk throughput penulisan yang tinggi dan menggunakan sintaks tulis yang efisien dan dapat dibaca manusia yang disebut protokol baris. Sebagai schema-on-write database, InfluxDB secara otomatis membuat database logis, tabel, dan skema mereka ketika Anda mulai menulis data, tanpa memerlukan pengaturan manual. Setelah skema dibuat, InfluxDB memvalidasi permintaan penulisan future terhadapnya sebelum menerima data baru, sambil tetap mengizinkan evolusi skema saat kebutuhan Anda berubah.

Struktur protokol garis

Protokol garis terdiri dari elemen-elemen penting berikut:

• Tabel: Pengidentifikasi string untuk tabel tempat data akan disimpan.

• (Opsional) Kumpulan tag: Pasangan nilai kunci yang dibatasi koma yang mewakili metadata (diindeks).

• Kumpulan bidang: Pasangan nilai kunci yang dibatasi koma yang mewakili pengukuran aktual.

• (Opsional) Timestamp: Stempel waktu Unix yang terkait dengan titik data hingga presisi nanodetik.

Nilai bidang dapat menjadi salah satu tipe data berikut:

• String (harus dikutip)

• Mengapung (misalnya, 23.4)

• Bilangan bulat (misalnya, 10i)

• Bilangan bulat yang tidak ditandatangani (misalnya, 10u)

• Boolean (benar/salah)

Protokol baris mengikuti sintaks umum ini:

myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

Contoh titik data menggunakan protokol baris:

home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600

Ini menciptakan titik di tabel “rumah” dengan:

• Tag: Room="Ruang Tamu”

• Bidang: temp=21.1 (mengambang), hum=35,9 (mengambang), co = 0 (bilangan bulat)

• Stempel waktu: 1735545600 (Unix detik)

Ikhtisar titik akhir API

InfluxDB 3 mendukung tiga titik akhir penulisan utama:

1. Native v3 API (/api/v3/write_lp): Titik akhir yang direkomendasikan untuk implementasi baru.

2. v2 Compatibility API (/api/v2/write): Untuk memigrasikan beban kerja InfluxDB v2.x.

3. v1 Compatibility API (/write): Untuk memigrasikan beban kerja InfluxDB v1.x.

Menggunakan Native v3 write API

/api/v3/write_lpTitik akhir adalah API InfluxDB 3 asli untuk menulis data protokol baris.

Format permintaan:

POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN

Parameter kueri:

Parameter	Deskripsi	Default
db	Nama database (wajib)	-
precision	Presisi stempel waktu (ns, us, ms, s)	Terdeteksi secara otomatis
accept_partial	Terima penulisan sebagian tentang kesalahan	true
no_sync	Akui sebelum kegigihan WAL	false

Contoh permintaan tulis:

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"

Tulis mode respons

Mode Standar (no_sync= salah)

• Menunggu data ditulis ke WAL (Write-Ahead Log) sebelum mengakui.

• Memberikan jaminan daya tahan.

• Latensi yang lebih tinggi karena ketekunan WAL menunggu.

• Direkomendasikan untuk data penting di mana daya tahan sangat penting.

Mode Cepat (no_sync= benar)

• Mengakui segera tanpa menunggu ketekunan WAL.

• Latensi tulis serendah mungkin.

• Risiko kehilangan data jika sistem crash sebelum WAL write selesai.

• Ideal untuk skenario throughput tinggi di mana kecepatan diprioritaskan daripada daya tahan absolut.

Penanganan menulis sebagian

accept_partialParameter mengontrol perilaku saat menulis batch berisi kesalahan:

accept_partialKapan true (default):

• Baris yang valid ditulis dengan sukses.

• Baris yang tidak valid ditolak.

• Mengembalikan status 400 dengan rincian tentang baris gagal.

• Berguna untuk operasi batch besar di mana beberapa kegagalan dapat diterima.

Ketika accept_partial adalah false:

• Seluruh batch ditolak jika ada baris yang gagal.

• Tidak ada data yang ditulis.

• Mengembalikan status 400 dengan rincian kesalahan.

• Memastikan all-or-nothing menulis semantik.

Kompatibilitas APIs

Kompatibilitas APIs memungkinkan migrasi tanpa batas beban kerja InfluxDB v1 atau v2 yang ada ke InfluxDB 3. Endpoint ini bekerja dengan library klien InfluxDB yang ada, Telegraf, dan integrasi pihak ketiga.

Perbedaan penting:

• Tag dalam tabel (pengukuran) tidak dapat diubah setelah dibuat.

• Tag dan bidang tidak dapat memiliki nama yang sama dalam tabel.

• Validasi skema diberlakukan saat menulis.

Kompatibilitas InfluxDB v2

/api/v2/writeTitik akhir menyediakan kompatibilitas mundur untuk klien 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'

Parameter API V2:

Parameter	Lokasi	Deskripsi
bucket *	String kueri	Peta ke nama database
precision	String kueri	Presisi stempel waktu (ns, us, ms, s, m, h)
Authorization	Header	Skema Pembawa atau Token
Content-Encoding	Header	gzip atau identitas

Kompatibilitas InfluxDB v1

/writeTitik akhir menyediakan kompatibilitas mundur untuk klien 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'

Opsi otentikasi V1:

• Otentikasi dasar: Token sebagai kata sandi (--user "any:TOKEN").

• Parameter kueri: p=TOKEN di URL.

• Bearer/Token header: Header otorisasi standar.

Parameter API V1:

Parameter	Lokasi	Deskripsi
db *	String kueri	Nama basis data
precision	String kueri	Presisi stempel waktu
p	String kueri	Token untuk autentikasi kueri
u	String kueri	Nama pengguna (diabaikan)
Authorization	Header	Beberapa skema didukung
Content-Encoding	Header	gzip atau identitas

Pustaka dan integrasi klien

Pustaka klien InfluxDB 3 resmi

Pustaka klien InfluxDB 3 menyediakan antarmuka bahasa asli untuk membangun dan menulis data deret waktu:

• Python: influxdb3-python

• Pergi: influxdb3-go

• JavaScript/Node.js: influxdb3-js

• Jawa: influxdb3-java

• C #: InfluxDB3.Client

Contoh: Klien 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)

Contoh: Go client

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})

Pustaka klien lama

Untuk beban kerja v1 dan v2 yang ada, Anda dapat terus menggunakan pustaka klien lama dengan titik akhir kompatibilitas:

Contoh: Node.js klien 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'
})

Praktik terbaik untuk menulis data

Saat menulis data, kami merekomendasikan yang berikut:

• Pengoptimalan Batch

  • Ukuran batch optimal: 5.000-10.000 baris atau 10MB per permintaan.

  • Gunakan kompresi (gzip) untuk muatan besar.

  • Urutkan tag berdasarkan kunci dalam urutan leksikografi untuk kinerja yang lebih baik.

• Presisi stempel waktu

  • Gunakan presisi paling kasar yang memenuhi kebutuhan Anda.

  • Secara eksplisit menentukan presisi untuk menghindari ambiguitas.

  • Pertahankan presisi yang konsisten di seluruh aplikasi Anda.

• Penanganan kesalahan

  • Menerapkan logika coba lagi untuk kegagalan sementara.

  • Gunakan accept_partial=true untuk operasi batch tangguh.

  • Pantau kesalahan penulisan melalui CloudWatch metrik.

• Penyempurnaan performa

  • Gunakan no_sync=true untuk skenario throughput tinggi.

  • Mendistribusikan tulisan di beberapa koneksi.

  • Gunakan writer/reader titik akhir untuk semua operasi penulisan.

• Pertimbangan skema

  • Tag tidak dapat diubah setelah dibuat.

  • Bidang dan tag tidak dapat berbagi nama yang sama.e

  • Skema desain dengan pola kueri dalam pikiran.

  • Jaga kardinalitas tag di bawah kendali.

Perbedaan penting dari versi sebelumnya:

• Tag yang tidak dapat diubah: Setelah tag dibuat dalam tabel, jenisnya tidak dapat diubah

• Tidak ada konflik tag/field nama: Tag dan bidang tidak dapat memiliki nama yang sama dalam tabel

• Schema-on-write: InfluxDB 3 memvalidasi tipe data saat menulis

• Pembuatan tabel otomatis: Tabel dibuat secara otomatis pada penulisan pertama

• Pemeriksaan tipe ketat: Jenis bidang harus tetap konsisten di semua penulisan

Dengan memanfaatkan API tulis yang sesuai dan mengikuti praktik terbaik ini, Anda dapat secara efisien menyerap data deret waktu ke dalam Timestream untuk instans InfluxDB 3 sambil mempertahankan kinerja tinggi dan integritas data.