Menulis titik data multi-nilai

Dokumen ini menjelaskan cara menulis titik data multi-nilai ke Time Series Database (TSDB) menggunakan titik akhir /api/mput. Setiap titik data termasuk dalam satu sumber data pada stempel waktu tertentu dan membawa nilai dari beberapa bidang metrik—misalnya, cpu, mem, dan load untuk sebuah server—dalam satu operasi penulisan.

Cara kerja

Titik data multi-nilai mengelompokkan beberapa nilai bidang metrik di bawah satu nama metrik, satu stempel waktu, dan satu set tag. Pendekatan ini berbeda dari model nilai tunggal (/api/put), di mana setiap bidang memerlukan titik data terpisah.

Semua permintaan menggunakan POST /api/mput dengan larik JSON dalam badan permintaan. Pilih mode penulisan dengan menambahkan parameter kueri ke URL:

Mode penulisan	Parameter kueri	Tanggapan
Sederhana	_(tidak ada)_	Hanya kode status
Statistik	`summary`	`success`, jumlah `failed`
Detail	`details`	`success`, `failed`, `errors` (kegagalan pertama)
Toleransi kesalahan	`ignoreErrors`	`success`, `failed`, `errors` (semua kegagalan)

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Akses jaringan ke titik akhir HTTP TSDB
Setidaknya satu pasangan kunci-nilai tag untuk setiap titik data

Pada Edisi Ketersediaan Tinggi, panjang nama metrik dapat mencapai 255 byte.

Kirim permintaan POST ke /api/mput dengan larik JSON berisi titik data dalam badan permintaan. Setiap titik data harus menyertakan metric, timestamp, fields, dan tags.

Permintaan

Titik akhir

POST /api/mput

Parameter kueri

Tambahkan parameter berikut ke URL untuk mengontrol format tanggapan. Parameter tanpa tipe bernilai true jika disertakan, terlepas dari nilai yang diberikan.

Parameter	Tipe	Bawaan	Deskripsi	Contoh
`summary`	Tanpa tipe	false	Mengembalikan statistik penulisan (jumlah `success` dan `failed`).	`/api/mput?summary`
`details`	Tanpa tipe	false	Mengembalikan statistik penulisan dan kesalahan penulisan pertama. Jika `summary` dan `details` keduanya disertakan, `details` memiliki prioritas lebih tinggi.	`/api/mput?details`
`sync_timeout`	Integer	0	Timeout dalam milidetik. `0` berarti tanpa timeout.	`/api/mput?sync&sync_timeout=60000`
`ignoreErrors`	Tanpa tipe	false	Melanjutkan penulisan titik data yang tersisa ketika salah satu gagal.	`/api/mput?ignoreErrors`

Isi Permintaan

Kirimkan larik JSON di mana setiap elemen merupakan titik data dengan bidang-bidang berikut:

Bidang	Tipe	Wajib	Batasan	Deskripsi
`metric`	String	Ya	Huruf, angka, dan `-_./():,[]='#`. Maksimal 255 byte pada Edisi Ketersediaan Tinggi.	Nama metrik.
`timestamp`	Long	Ya	Lihat Aturan stempel waktu.	Stempel waktu titik data, dalam detik atau milidetik.
`fields`	Map	Ya	Nama bidang mengikuti aturan karakter yang sama seperti `metric`. Nilai harus bertipe STRING, NUMBER, atau BOOLEAN. Nilai STRING dapat mencapai 20 KB.	Pasangan kunci-nilai bidang metrik.
`tags`	Map	Ya	Huruf, angka, dan `-_./():,[]='#`. Diperlukan minimal satu pasangan kunci-nilai tag. Nilai non-string dikonversi ke STRING secara otomatis.	Pasangan kunci-nilai tag untuk titik data.

Contoh permintaan

POST /api/mput
Content-Type: application/json

[
  {
    "metric": "wind",
    "fields": {
      "speed": 20.8,
      "level": 4,
      "direction": "East",
      "description": "Fresh breeze"
    },
    "tags": {
      "sensor": "IOTE_8859_0001",
      "city": "hangzhou",
      "province": "zhejiang",
      "country": "china"
    },
    "timestamp": 1346846400
  },
  {
    "metric": "wind",
    "fields": {
      "speed": 40.2,
      "level": 6,
      "direction": "South",
      "description": "Fresh breeze"
    },
    "tags": {
      "sensor": "IOTE_8859_0002",
      "city": "hangzhou",
      "province": "zhejiang",
      "country": "china"
    },
    "timestamp": 1346846401
  }
]

Aturan stempel waktu

TSDB menentukan satuan stempel waktu berdasarkan nilai numeriknya. Aturan ini berlaku untuk /api/put, /api/mput, /api/query, dan /api/mquery.

Rentang nilai	Satuan	Rentang tanggal yang sesuai
4.294.968 – 4.294.967.295	Detik	1970-02-20 01:02:48 – 2106-02-07 14:28:15
4.294.967.296 – 9.999.999.999.999	Milidetik	1970-02-20 01:02:47.296 – 2286-11-21 01:46:39.999
Di luar kedua rentang tersebut	Tidak valid	—

Mode penulisan

Pilih mode penulisan berdasarkan tingkat detail tanggapan yang dibutuhkan oleh aplikasi Anda.

Mode sederhana

Tidak memerlukan parameter kueri. Mengembalikan HTTP 204 jika berhasil. Jika gagal, mengembalikan kode kesalahan dan pesan kesalahan.

Gunakan mode ini untuk data pemantauan umum di mana kesalahan penulisan tidak diharapkan dan logika pengulangan ditangani secara eksternal.

Mode statistik

Tambahkan ?summary ke URL permintaan. Mengembalikan jumlah success dan failed terlepas dari hasil penulisan.

{
  "success": 20,
  "failed": 0
}

Bidang tanggapan	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang ditulis. Dihitung menggunakan model nilai tunggal: setiap bidang dalam titik data multi-nilai dihitung secara terpisah.
`failed`	Integer	Jumlah titik data yang gagal.

Pada mode statistik, semua titik data dalam satu permintaan api/mput akan berhasil atau gagal secara bersamaan. Jika ada satu titik data yang gagal, failed mencerminkan jumlah total titik data dalam permintaan tersebut.

Gunakan mode ini saat Anda perlu melacak statistik throughput penulisan.

Mode detail

Tambahkan ?details ke URL permintaan. Memperluas mode statistik dengan menyertakan kegagalan penulisan pertama dalam tanggapan.

Bidang tanggapan	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang ditulis.
`failed`	Integer	Jumlah titik data yang gagal.
`errors`	Array	Detail titik data pertama yang gagal, termasuk titik datanya dan penyebab kegagalannya.

Pada mode detail, semua titik data dalam permintaan berhasil atau gagal secara bersamaan. Larik errors hanya berisi kegagalan pertama. Periksa failed untuk mengetahui jumlah total kegagalan.

Gunakan mode ini saat Anda perlu mengidentifikasi penyebab kegagalan penulisan.

Mode toleransi kesalahan

Tambahkan ?ignoreErrors ke URL permintaan. Menulis setiap titik data secara independen—kegagalan pada satu titik data tidak menghentikan penulisan titik data lainnya.

Bidang tanggapan	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang ditulis.
`failed`	Integer	Jumlah titik data yang gagal.
`errors`	Array	Semua titik data yang gagal, masing-masing disertai titik datanya dan penyebab kegagalannya. Titik data yang tidak tercantum dalam `errors` berhasil ditulis.

Mengembalikan HTTP 200 jika setidaknya satu titik data berhasil ditulis. Mengembalikan kode status selain 200 hanya jika semua titik data gagal karena kesalahan kritis seperti kegagalan penyimpanan dasar.

Gunakan mode ini saat permintaan Anda mungkin berisi campuran titik data valid dan tidak valid, dan Anda ingin memaksimalkan jumlah titik data yang berhasil ditulis.

Diferensiasi API

Gunakan titik akhir yang tepat untuk setiap operasi:

Operasi	Titik akhir
Menulis titik data nilai tunggal	`POST /api/put`
Menulis titik data multi-nilai	`POST /api/mput`
Mengkueri titik data nilai tunggal	`GET /api/query`
Mengkueri titik data multi-nilai	`GET /api/mquery`