Tulis titik data multi-nilai -

Topik ini menjelaskan mode penulisan dan respons untuk titik data multi-nilai.

Model Data Multi-Nilai untuk Data Deret Waktu

Model data multi-nilai dibuat berdasarkan sumber data. Setiap entri data dibuat untuk sumber data tertentu pada titik waktu tertentu dan berisi nilai dari beberapa bidang data deret waktu. Sebagai contoh, sebuah entri data dapat berisi nilai dari bidang data deret waktu berikut dari server: cpu, mem, dan load. Ini memungkinkan Anda mengelola bidang-bidang tersebut secara bersamaan.

Gunakan Model Data Multi-Nilai untuk Menulis Data

Jalur Permintaan dan Metode

Jalur permintaan	Metode permintaan	Deskripsi
/api/mput	POST	Menulis beberapa titik data sekaligus.

Penting

Anda harus memanggil operasi API yang berbeda untuk menulis titik data bernilai tunggal dan titik data multi-nilai. Untuk menulis titik data bernilai tunggal, panggil operasi /api/put. Untuk menanyakan titik data multi-nilai, panggil operasi /api/mquery. Untuk menulis titik data bernilai tunggal, panggil operasi /api/query.

Parameter Permintaan

Parameter	Tipe	Wajib	Deskripsi	Bawaan	Contoh
summary	Tidak bertipe	Tidak	Menentukan apakah akan mengembalikan ringkasan.	false	/api/mput?summary
details	Tidak bertipe	Tidak	Menentukan apakah akan mengembalikan detail.	false	/api/mput?details
sync_timeout	Integer	Tidak	Periode timeout. Satuan: milidetik. Nilai 0 menentukan bahwa permintaan tidak bisa timeout.	0	/api/mput/?sync&sync_timeout=60000
ignoreErrors	Tidak bertipe	Tidak	Menentukan apakah akan mengabaikan kesalahan penulisan dan melanjutkan penulisan titik data lainnya.	false	/api/mput/?ignoreErrors

Catatan

Sistem menentukan bahwa nilai parameter tanpa tipe adalah benar jika parameter ditentukan. Sebagai contoh, sistem menentukan bahwa nilai parameter summary adalah benar terlepas dari apakah Anda menyetel parameter ke true atau false.
Jika Anda menyertakan parameter details dan parameter summary dalam kueri yang sama, operasi API mengembalikan nilai parameter details.

Konten Permintaan

Tentukan titik data dalam format JSON. Tabel berikut menjelaskan parameter untuk titik data.

Parameter	Tipe	Wajib	Batas	Deskripsi	Contoh
metric	String	Ya	Nilai hanya dapat berisi huruf, angka, dan karakter khusus berikut: `-_./():,[]=‘#`	Nama metric yang ingin Anda simpan.	sys.cpu Catatan Pada Edisi Ketersediaan Tinggi, nama metric dapat memiliki panjang hingga 255 byte.
timestamp	Long	Ya	N/A	Timestamp diukur dalam detik atau milidetik. Untuk informasi lebih lanjut tentang aturan untuk menentukan unit, lihat bagian "Unit timestamp" dalam topik ini.	1499158925
fields	Map	Ya	Batas pada nama field sama dengan batas pada nama metric. Tipe data nilai field harus STRING, NUMBER, atau BOOLEAN.	Nilai dari field.	“fields” : {“speed” : 20.8, “level” : 4, “direction” : “East”, “description” : “Fresh breeze”}
tags	Map	Ya	Nilai dapat berisi huruf, angka, dan karakter khusus berikut: `-_./():,[]=‘#`	Pasangan key-value tag. Key tag dan value tag adalah string karakter. Tentukan setidaknya satu pasangan key-value tag.	{"host":"web01"}. Key tag dan value tag yang bukan tipe STRING secara eksplisit dikonversi ke tipe STRING.

Unit Timestamp

Bagian ini menjelaskan aturan untuk menentukan unit timestamp. Aturan ini berlaku untuk operasi API berikut: /api/put, /api/mput, /api/query, dan /api/mquery. /api/put dan /api/mput digunakan untuk menulis data. /api/query dan /api/mquery digunakan untuk menanyakan data. Timestamp dapat diukur dalam detik atau milidetik. Time Series Database (TSDB) menggunakan aturan berikut untuk menentukan unit timestamp berdasarkan nilai numerik:

Jika nilai berada dalam rentang [4.294.968, 4.294.967.295], TSDB menentukan bahwa timestamp diukur dalam detik. Dalam hal ini, rentang tanggal dan waktu yang sesuai adalah [1970-02-20 01:02:48, 2106-02-07 14:28:15].
Jika nilai berada dalam rentang [4.294.967.296, 9.999.999.999.999], unitnya adalah milidetik. Dalam hal ini, rentang tanggal dan waktu adalah [1970-02-20 01:02:47.296, 2286-11-21 01:46:39.999].
Jika nilai berada dalam rentang (-∞, 4.294.968) atau (9.999.999.999.999, +∞), timestamp tidak valid.

Deskripsi Nilai dalam Titik Data Multi-Nilai

Nilai tipe data STRING dapat berisi semua karakter dan dapat disimpan dalam format JSON. Ukuran nilai string tidak boleh melebihi 20 KB.

Kode berikut memberikan contoh cara menulis titik data multi-nilai:

Baris permintaan: POST/api/mput. Body permintaan:

[
{
"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
}
]

Mode penulisan dan respons

TSDB mendukung empat mode penulisan. Untuk menggunakan masing-masing mode, konfigurasikan parameter permintaan berdasarkan instruksi berikut:

Mode Sederhana

Untuk menggunakan mode ini, jangan konfigurasikan parameter saat Anda memanggil operasi api/mput. Jika data berhasil ditulis ke TSDB, kode status 204 dikembalikan. Jika data gagal ditulis, hanya kode kesalahan dan pesan kesalahan yang sesuai yang dikembalikan.

Mode ini cocok untuk melaporkan data pemantauan bisnis umum.
Mode Statistik

Untuk menggunakan mode ini, konfigurasikan parameter summary saat Anda memanggil operasi api/mput. Parameter success dan failed dikembalikan, terlepas dari apakah data berhasil ditulis ke TSDB. Ini membantu Anda mengumpulkan statistik bisnis Anda. Parameter success menunjukkan jumlah titik data yang berhasil ditulis. Parameter failed menunjukkan jumlah titik data yang gagal ditulis.

Parameter
Tipe
Deskripsi
success
Integer
Jumlah titik data yang berhasil ditulis seperti yang diharapkan.
failed
Integer
Jumlah titik data yang gagal ditulis.

Contoh kebijakan:
```
{
    "failed":0,
    "success": 20
}
```
Penting
- Dalam mode statistik, titik data dalam permintaan api/mput semuanya berhasil ditulis atau semuanya gagal ditulis. Jika penulisan data gagal, parameter failed menunjukkan jumlah titik data yang ditentukan dalam permintaan Anda.
- Saat Anda menulis titik data multi-nilai, nilai parameter success atau failed dihitung berdasarkan model data bernilai tunggal. Ini menunjukkan bahwa satu titik data multi-nilai dihitung lebih dari satu kali. Jumlah penghitungan titik data multi-nilai sama dengan jumlah field dari titik data multi-nilai tersebut.
Mode statistik cocok untuk melaporkan data pemantauan bisnis umum yang memerlukan statistik pada data yang dilaporkan.

Mode Rinci

Mode rinci adalah perluasan dari mode statistik. Untuk menggunakan mode ini, konfigurasikan parameter details saat Anda memanggil operasi api/mput. Parameter success, failed, dan errors dikembalikan terlepas dari apakah data berhasil ditulis ke TSDB. Parameter success menunjukkan jumlah titik data yang berhasil ditulis. Parameter failed menunjukkan jumlah titik data yang gagal ditulis. Parameter errors menunjukkan penyebab langsung kegagalan penulisan.

Parameter	Tipe	Deskripsi
success	Integer	Jumlah titik data yang berhasil ditulis seperti yang diharapkan.
failed	Integer	Jumlah titik data yang gagal ditulis.
errors	Array	Penyebab langsung kegagalan penulisan titik data pertama yang gagal ditulis. Nilainya adalah array yang terdiri dari informasi tentang titik data dan penyebab kegagalan.

Penting

Dalam mode statistik, titik data dalam permintaan api/mput semuanya berhasil ditulis atau semuanya gagal ditulis. Nilai errors hanya berisi informasi tentang titik data pertama yang gagal ditulis dan penyebab langsung kegagalannya. Untuk melihat jumlah titik data yang gagal ditulis, lihat nilai parameter failed.

Mode ini cocok untuk melaporkan data pemantauan bisnis yang memerlukan statistik pada data yang dilaporkan dan lokasi kesalahan.

Mode Toleransi Kesalahan

Untuk menggunakan mode ini, konfigurasikan parameter ignoreErrors saat Anda memanggil operasi api/mput. Saat Anda mengirim permintaan untuk menulis batch titik data ke TSDB dalam mode toleransi kesalahan, kegagalan penulisan satu titik data tidak berpengaruh pada penulisan titik data lainnya. Mode ini memastikan bahwa sebagian besar titik data dapat ditulis ke TSDB ketika ada titik data valid dan tidak valid dalam batch yang sama. Titik data yang gagal ditulis dienumerasi dalam respons. Respons berisi parameter yang sama dengan yang dikembalikan saat Anda mengonfigurasikan parameter details dalam permintaan Anda. Namun, parameter errors berisi nama setiap titik data yang gagal ditulis dan penyebab kegagalannya. Titik data yang tidak termasuk dalam nilai parameter errors berhasil ditulis ke TSDB seperti yang diharapkan.

Parameter	Tipe	Deskripsi
success	Integer	Jumlah titik data yang berhasil ditulis seperti yang diharapkan.
failed	Integer	Jumlah titik data yang gagal ditulis.
errors	Array	Array dari setiap titik data yang gagal ditulis dan penyebab kegagalannya yang sesuai.

Penting

Dalam mode toleransi kesalahan, jika tidak semua titik data dalam batch gagal ditulis, kode status 200 dikembalikan. Jika semua titik data dalam batch gagal ditulis karena kesalahan kritis seperti kegagalan penyimpanan bawah, kode status selain 200 dikembalikan. Dalam mode toleransi kesalahan, parameter failed menunjukkan jumlah titik data yang gagal ditulis.

Mode ini cocok untuk melaporkan data pemantauan skenario bisnis di mana integritas data yang dilaporkan perlu dipastikan, kegagalan perlu diselesaikan, dan penulisan ulang titik data yang gagal ditulis perlu dilakukan.