Tulis data - - 阿里云

Jalur permintaan dan metode

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

Parameter permintaan

Parameter	Tipe	Diperlukan	Deskripsi	Nilai default	Contoh
summary	Tidak bertipe	Tidak	Menentukan apakah akan mengembalikan ringkasan.	false	/api/put?summary
details	Tidak bertipe	Tidak	Menentukan apakah akan mengembalikan detail.	false	/api/put?details
sync_timeout	Integer	Tidak	Periode timeout. Satuan: milidetik. Nilai 0 menunjukkan bahwa permintaan tidak pernah timeout.	0	/api/put/?sync&sync_timeout=60000
ignoreErrors	Tidak bertipe	Tidak	Menentukan apakah akan mengabaikan pengecualian penulisan beberapa titik data.	false	/api/put/?ignoreErrors

Catatan:

Sistem menentukan bahwa nilai parameter yang tidak bertipe adalah true jika parameter tersebut dikonfigurasi. Sebagai contoh, sistem menentukan bahwa nilai parameter summary adalah true terlepas dari apakah Anda mengatur parameter ke true atau false.
Jika Anda menentukan parameter details dan parameter summary, operasi API mengembalikan detail.

Parameter permintaan

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

Parameter	Tipe	Diperlukan	Batas	Deskripsi	Contoh
metric	String	Ya	Nilainya hanya dapat berisi huruf, angka, dan karakter khusus berikut: `-_./():,[]='#`	Nama metrik yang akan disimpan.	sys.cpu Catatan Pada Edisi Ketersediaan Tinggi, nama metrik dapat memiliki panjang hingga 255 byte.
timestamp	Long	Ya	Tidak ada	Timestamp diukur dalam detik atau milidetik. Untuk informasi lebih lanjut tentang aturan untuk menentukan satuan, lihat bagian Satuan timestamp dalam topik ini.	1499158925
value	Long,Double,String,Boolean	Ya	Tidak ada	Nilai dalam titik data.	42.5, true
tags	Map	Tidak	Nilainya hanya dapat berisi huruf, angka, dan karakter khusus berikut: `-_./():,[]='#`	Pasangan kunci-nilai tag. Kunci tag dan nilai tag adalah string karakter. Tentukan setidaknya satu pasangan kunci-nilai tag.	{"host":"web01"}. Kunci tag dan nilai tag yang bukan tipe STRING secara eksplisit dikonversi ke tipe STRING.

Satuan Timestamp

Bagian ini menjelaskan aturan untuk menentukan satuan timestamp. Aturan ini berlaku untuk operasi API berikut: /api/put dan api/query. Operasi /api/put digunakan untuk menulis data, sedangkan /api/query digunakan untuk meminta data.

Timestamp dapat diukur dalam detik atau milidetik. Time Series Database (TSDB) menggunakan aturan berikut untuk menentukan satuan timestamp berdasarkan nilai numerik:

Jika nilainya berada dalam rentang [4.294.968, 4.294.967.295], satuannya adalah detik. Dalam hal ini, rentang tanggal dan waktu adalah [1970-02-20 01:02:48, 2106-02-07 14:28:15].
Jika nilainya berada dalam rentang [4.294.967.296, 9.999.999.999.999], satuannya 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 nilainya berada dalam rentang (-∞, 4.294.968) atau (9.999.999.999.999, +∞), timestamp tidak valid.

Deskripsi Nilai dalam Titik Data

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

Deskripsi Tag

Saat Anda menulis data dalam deret waktu, Anda hanya dapat menentukan sejumlah terbatas kunci tag. Jumlah maksimum kunci tag bervariasi berdasarkan jenis instance TSDB, seperti yang tercantum dalam tabel berikut.

Jenis instance.	Jumlah maksimum kunci tag dalam satu deret waktu
mLarge	16
Large	16
3xLarge	20
4xLarge	20
6xLarge	20
12xLarge	20
24xLarge	24
48xLarge	24
96xLarge	24

Contoh Permintaan

Baris Permintaan: POST /api/put

Baris Permintaan:

[
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":18,
"tags":{
"host":"web01",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":9,
"tags":{
"host":"web02",
"dc":"lga"
}
},
{
"metric":"sys.cpu.alter",
"timestamp":1346846400,
"value":"High CPU Load",
"tags":{
"host":"web03",
"dc":"lga"
}
},
{
"metric":"sys.cpu.nice",
"timestamp":1346846400,
"value":true,
"tags":{
"host":"web04",
"dc":"lga"
}
}
]

Mode tulis dan respons

TSDB mendukung empat mode tulis. Untuk menggunakan masing-masing mode, konfigurasikan parameter permintaan sesuai dengan instruksi berikut:

Mode Sederhana

Untuk menggunakan mode ini, jangan konfigurasikan parameter saat Anda memanggil operasi api/put. Jika data ditulis ke TSDB sesuai harapan, kode status 204 dikembalikan. Jika data gagal ditulis, hanya kode kesalahan dan pesan kesalahan yang bersangkutan 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/put. Parameter success dan failed dikembalikan, terlepas dari apakah data ditulis ke TSDB sesuai harapan. 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 ditulis sesuai harapan.
failed
Integer
Jumlah titik data yang gagal ditulis.

Contoh:
```
{
    "failed":0,
    "success": 20
}
```
Penting
Dalam mode statistik, titik data dalam permintaan api/put semuanya ditulis sesuai harapan atau semuanya gagal ditulis. Jika penulisan data gagal, parameter failed menunjukkan jumlah titik data yang ditentukan dalam permintaan Anda.

Mode statistik cocok untuk melaporkan data pemantauan bisnis umum yang memerlukan statistik pada data yang dilaporkan.

Mode Rinci

Mode rinci adalah ekstensi dari mode statistik. Untuk menggunakan mode ini, konfigurasikan parameter details saat Anda memanggil operasi api/put. Parameter success, failed, dan errors dikembalikan terlepas dari apakah data ditulis ke TSDB sesuai harapan. 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 ditulis sesuai harapan.
failed	Integer	Jumlah titik data yang gagal ditulis.
errors	Array	Penyebab langsung kegagalan titik data pertama yang gagal ditulis. Nilainya adalah array yang terdiri dari informasi tentang titik data dan penyebab kegagalan.

Contoh:

{
    "errors":[{
            "datapoint":{
                "metric":"sys.cpu.nice",
                "timestamp":1365465600,
                "value":"NaN",
                "tags":{
                    "host":"web01"
                }
            },
            "error":"Tidak dapat mengurai nilai menjadi angka"
        }],
    "failed":1,
    "success":0
}

Penting

Dalam mode rinci, titik data dalam satu permintaan yang memanggil operasi api/put semuanya ditulis atau semuanya gagal ditulis. Nilai errors hanya berisi informasi tentang titik data pertama yang gagal ditulis dan penyebab langsung kegagalan. 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/put. Saat Anda mengirim permintaan untuk menulis batch titik data ke TSDB dalam mode toleransi kesalahan, kegagalan penulisan satu titik data tidak berdampak pada penulisan titik data lainnya. Mode ini memastikan bahwa sebagian besar titik data dapat ditulis ke TSDB ketika titik data valid dan tidak valid ada dalam batch yang sama. Titik data yang gagal ditulis diuraikan 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 ditulis ke TSDB sesuai harapan.

Parameter	Tipe	Deskripsi
success	Integer	Jumlah titik data yang ditulis sesuai harapan.
failed	Integer	Jumlah titik data yang gagal ditulis.
errors	Array	Array setiap titik data yang gagal ditulis dan penyebab kegagalan yang sesuai.

Contoh:

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 dasar, 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 bisnis yang memerlukan integritas data yang dilaporkan dan perbaikan kesalahan serta penulisan ulang titik data yang gagal.