Tulis data point batch ke TSDB melalui POST /api/put - Time Series Database - Alibaba Cloud -

Gunakan POST /api/put untuk menulis satu atau beberapa titik data ke Time Series Database (TSDB) dalam satu permintaan.

Mulai cepat

Contoh berikut menulis dua titik data menggunakan curl. Ganti nilai placeholder sebelum menjalankan.

curl -X POST 'http://<your-tsdb-endpoint>/api/put?summary' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "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"}
    }
  ]'

Placeholder	Deskripsi	Contoh
`<your-tsdb-endpoint>`	Alamat instans TSDB Anda	`tsdb.example.com:4242`

Endpoint

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

Parameter kueri

Tambahkan parameter berikut ke URL permintaan untuk mengontrol format respons.

Parameter	Tipe	Wajib	Bawaan	Deskripsi	Contoh
`summary`	Untyped	Tidak	false	Mengembalikan jumlah penulisan yang berhasil dan gagal	`/api/put?summary`
`details`	Untyped	Tidak	false	Mengembalikan jumlah ditambah detail kesalahan untuk titik data yang gagal	`/api/put?details`
`sync_timeout`	Integer	Tidak	0	Timeout dalam milidetik. `0` berarti tanpa timeout.	`/api/put?sync&sync_timeout=60000`
`ignoreErrors`	Untyped	Tidak	false	Melanjutkan penulisan titik data yang tersisa ketika salah satu gagal	`/api/put?ignoreErrors`

Untuk parameter untyped, sistem memperlakukan parameter tersebut sebagai true setiap kali muncul di URL, terlepas dari nilai yang diberikan. Misalnya, baik ?summary=true maupun ?summary=false mengaktifkan mode ringkasan. Jika Anda menentukan kedua parameter details dan summary, API akan mengembalikan detail.

Badan permintaan

Tentukan titik data sebagai array JSON. Setiap elemen merepresentasikan satu titik data.

Parameter	Tipe	Wajib	Batasan	Deskripsi	Contoh
`metric`	String	Ya	Huruf, angka, dan `-` `_` `.` `/` `(` `)` `:` `,` `[` `]` `=` `'` `#`	Nama metrik	`sys.cpu.nice`
`timestamp`	Long	Ya	Lihat Aturan timestamp	Timestamp Unix dalam detik atau milidetik	`1346846400`
`value`	Long, Double, String, Boolean	Ya	Nilai string tidak boleh melebihi 20 KB	Nilai titik data	`18`, `"High CPU Load"`, `true`
`tags`	Map	Tidak	Set karakter sama seperti `metric`; minimal satu pasangan kunci-nilai diperlukan	Pasangan kunci-nilai tag	`{"host": "web01", "dc": "lga"}`

Dalam Edisi Ketersediaan Tinggi, nama metrik dapat memiliki panjang hingga 255 byte.

Tag yang bukan bertipe String secara otomatis dikonversi ke String.

Aturan timestamp

TSDB secara otomatis menentukan apakah timestamp dalam satuan detik atau milidetik berdasarkan nilai numeriknya. Aturan yang sama berlaku untuk /api/put dan /api/query.

Rentang nilai	Unit	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 dan respons

Secara bawaan, POST /api/put mengembalikan HTTP 204 tanpa badan respons jika semua titik data berhasil ditulis. Tambahkan parameter kueri untuk mendapatkan detail respons tambahan atau untuk mengisolasi kegagalan penulisan individual.

Mode sederhana (bawaan)

Kirim permintaan tanpa parameter mode.

Berhasil: HTTP 204, tanpa badan respons
Gagal: kode kesalahan HTTP dan pesan kesalahan

Gunakan mode ini untuk data pemantauan umum yang membutuhkan overhead minimal.

Mode statistik

Tambahkan ?summary untuk mendapatkan jumlah keberhasilan dan kegagalan.

POST /api/put?summary

Parameter respons:

Parameter	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang berhasil ditulis
`failed`	Integer	Jumlah titik data yang gagal ditulis

Contoh respons:

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

Penting

Dalam mode statistik, semua titik data dalam satu permintaan berhasil atau gagal secara bersamaan. Jika ada satu penulisan yang gagal, failed sama dengan jumlah total titik data dalam permintaan tersebut.

Gunakan mode ini ketika Anda perlu melacak berapa banyak titik data yang diterima.

Mode detail

Tambahkan ?details untuk mendapatkan informasi kesalahan beserta jumlah keberhasilan dan kegagalan. Mode detail merupakan perluasan dari mode statistik.

POST /api/put?details

Parameter respons:

Parameter	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang berhasil ditulis
`failed`	Integer	Jumlah titik data yang gagal ditulis
`errors`	Array	Titik data pertama yang gagal dan penyebab kegagalannya

Contoh respons:

{
  "errors": [
    {
      "datapoint": {
        "metric": "sys.cpu.nice",
        "timestamp": 1365465600,
        "value": "NaN",
        "tags": {"host": "web01"}
      },
      "error": "Unable to parse value to a number"
    }
  ],
  "failed": 1,
  "success": 0
}

Penting

Dalam mode detail, semua titik data dalam satu permintaan berhasil atau gagal secara bersamaan. Array errors hanya berisi titik data pertama yang gagal. Untuk mengetahui berapa banyak titik data yang gagal, periksa parameter failed.

Gunakan mode ini ketika Anda perlu menemukan lokasi kegagalan penulisan.

Mode toleransi kesalahan

Tambahkan ?ignoreErrors untuk memungkinkan permintaan melanjutkan penulisan titik data yang tersisa ketika salah satu gagal.

POST /api/put?ignoreErrors

Parameter respons:

Parameter	Tipe	Deskripsi
`success`	Integer	Jumlah titik data yang berhasil ditulis
`failed`	Integer	Jumlah titik data yang gagal ditulis
`errors`	Array	Setiap titik data yang gagal dan penyebab kegagalannya

Penting

Berbeda dengan mode statistik dan detail, mode toleransi kesalahan tidak memperlakukan permintaan secara atomik — kegagalan pada satu titik data tidak memengaruhi yang lain. Array errors berisi setiap titik data yang gagal, bukan hanya yang pertama. Titik data yang tidak tercantum dalam errors telah berhasil ditulis.

Jika sebagian (tetapi tidak semua) titik data gagal: HTTP 200
Jika semua titik data gagal karena kesalahan kritis (seperti kegagalan penyimpanan dasar): kode status non-200

Gunakan mode ini ketika Anda perlu memaksimalkan jumlah titik data yang ditulis dan menangani kegagalan individual secara terpisah.

Batasan

Jumlah maksimum kunci tag per deret waktu

Jumlah maksimum kunci tag dalam satu deret waktu bergantung pada tipe instans.

Tipe instans	Jumlah maksimum kunci tag
mLarge	16
Large	16
3xLarge	20
4xLarge	20
6xLarge	20
12xLarge	20
24xLarge	24
48xLarge	24
96xLarge	24

Nilai string

Nilai string dapat berisi karakter apa pun dan dapat disimpan dalam format JSON. Ukuran maksimum nilai string adalah 20 KB.