Gunakan api query last HTTP API untuk kueri titik data terbaru dari deret waktu-Time Series Database-Alibaba Cloud -

Menjalankan kueri untuk mendapatkan titik data terbaru dalam satu atau beberapa deret waktu. Sepenuhnya kompatibel dengan OpenTSDB.

Endpoint

POST /api/query/last

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi	Contoh
`queries`	Array	Ya	Subkueri yang akan dijalankan. Setiap subkueri menargetkan metrik atau TSUID.	Lihat Parameter subkueri.
`timestamp`	Long	Tidak	Stempel waktu UNIX yang digunakan sebagai acuan kueri, dalam satuan detik atau milidetik. Jika tidak ditentukan, kueri menggunakan stempel waktu saat ini.	`1539763573`
`hint`	Map	Tidak	Petunjuk kueri yang mengontrol indeks mana yang digunakan. Berlaku untuk semua subkueri dalam permintaan.	Lihat hint.
`limit`	Map	Tidak	Mengembalikan beberapa titik data terbaru per deret waktu, bukan hanya satu.	Lihat limit.

Parameter subkueri

Setiap subkueri dalam array queries harus menargetkan metrik atau TSUID.

Subkueri Metrik

Parameter	Tipe	Wajib	Deskripsi	Contoh
`metric`	String	Ya	Metrik yang dikueri.	`cpu.usage`
`tags`	Map	Tidak	Pasangan kunci-nilai tag untuk memfilter kueri.	`{"host_name": "host1"}`
`hint`	Map	Tidak	Petunjuk kueri yang hanya berlaku untuk subkueri ini.	Lihat hint.

Penting

Hanya parameter tags yang didukung untuk pemfilteran. Parameter filters tidak didukung.

Subkueri TSUID

Parameter	Tipe	Wajib	Deskripsi	Contoh
`tsuids`	Array	Ya	TSUID dari deret waktu yang dikueri.	`["00005B00005C0000F000005D0000EE00005E0000EF"]`

Penting

Untuk mendapatkan TSUID suatu deret waktu, panggil operasi /api/search/lookup. Edisi Ketersediaan Tinggi TSDB: Parameter tsuid diterima tetapi tidak berlaku. Operasi /api/search/lookup tidak mengembalikan TSUID pada edisi ketersediaan tinggi.

Anda dapat menyertakan subkueri metrik dan subkueri TSUID dalam satu permintaan yang sama.

Contoh permintaan

Permintaan berikut menjalankan dua subkueri: subkueri metrik untuk cpu.usage pada host1, dan subkueri TSUID untuk dua deret waktu.

POST /api/query/last

{
    "queries": [
        {
            "metric": "cpu.usage",
            "tags": {
                "host_name": "host1"
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

Elemen respons

Kode status 200 menunjukkan keberhasilan. Badan respons berupa array JSON, di mana setiap objek merepresentasikan titik data terbaru dari deret waktu yang sesuai. Jika tidak ada deret waktu yang cocok dengan kriteria kueri, array kosong dikembalikan.

Parameter	Deskripsi
`metric`	Nama metrik.
`timestamp`	Stempel waktu dari titik data terbaru.
`value`	Nilai metrik pada stempel waktu tersebut.
`tags`	Pasangan tag dari titik data tersebut. Setiap tag terdiri dari kunci tag dan nilai tag.
`tsuid`	ID dari deret waktu.

Contoh Respons

[{
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 30.3,
    "tags": {
        "host_name": "host1"
    },
    "tsuid": "00005B00005C00001D"
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 25.6,
    "tags": {
        "host_name": "host2",
        "cluster": "cluster1",
        "zone": "zone1"
    },
    "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE"
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 43.1,
    "tags": {
        "host_name": "host3",
        "cluster": "cluster1",
        "zone": "zone1"
    },
    "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF"
}]

hint

Gunakan petunjuk kueri untuk mengurangi waktu respons dengan mengontrol indeks mana yang digunakan oleh mesin kueri.

Didukung sejak: TSDB V2.6.1

Hanya parameter tagk yang didukung di dalam petunjuk. Tetapkan setiap kunci tag ke 0 atau 1:

0: jangan gunakan indeks untuk kunci tag ini
1: gunakan indeks untuk kunci tag ini

Semua nilai dalam tagk harus sama — mencampur 0 dan 1 dalam satu petunjuk akan mengembalikan error.

Petunjuk dapat berlaku untuk satu subkueri atau seluruh permintaan. Tetapkan hint di dalam objek subkueri untuk membatasi cakupannya hanya pada subkueri tersebut; tetapkan hint di tingkat atas untuk menerapkannya ke semua subkueri.

Petunjuk yang Dibatasi pada Subkueri

{
    "queries": [
        {
            "metric": "sys.cpu.nice",
            "tags": {
                "host": "web01"
            },
            "hint": {
                "tagk": {
                    "dc": 1
                }
            }
        }
    ]
}

Petunjuk yang Diterapkan ke Semua Subkueri

{
    "queries": [
        {
            "metric": "sys.cpu.nice",
            "tags": {
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 1
        }
    }
}

Kasus Error

Mencampur 0 dan 1 dalam map tagk yang sama mengembalikan HTTP 400. Permintaan berikut memicu error ini:

{
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 1,
            "host": 0
        }
    }
}

{
    "error": {
        "code": 400,
        "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

Memberikan nilai selain 0 atau 1 (misalnya, 100) juga mengembalikan HTTP 400. Permintaan berikut memicu error ini:

{
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 100
        }
    }
}

{
    "error": {
        "code": 400,
        "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

limit

Secara default, /api/query/last mengembalikan satu titik data per deret waktu. Tetapkan parameter limit untuk mengembalikan beberapa titik data terbaru per deret waktu dalam rentang waktu tertentu.

Parameter	Tipe	Wajib	Deskripsi	Contoh
`size`	Integer	Ya	Jumlah maksimum titik data yang dikembalikan per deret waktu.	`5`
`from`	Long	Ya	Awal rentang waktu yang dikueri, dalam bentuk stempel waktu UNIX.	`1346846400`

Contoh

Data berikut ditulis ke empat deret waktu, dengan dua titik data per deret waktu:

[
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv1"}, "timestamp": 1514736040, "value": 1},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv1"}, "timestamp": 1514736050, "value": 2},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv1"}, "timestamp": 1514736060, "value": 3},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv1"}, "timestamp": 1514736070, "value": 4},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv2"}, "timestamp": 1514736080, "value": 5},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv2"}, "timestamp": 1514736090, "value": 6},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv2"}, "timestamp": 1514736100, "value": 7},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv2"}, "timestamp": 1514736110, "value": 8}
]

Permintaan ini menetapkan size ke 2 dan mengkueri rentang 1514736040 hingga 1514736100, yang berisi tujuh titik data:

{
    "timestamp": 1514736100,
    "limit": {
        "size": 2,
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric"
        }
    ]
}

Respons mengembalikan hingga dua titik data per deret waktu dalam rentang waktu tersebut:

[
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "0200000200000200****",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "0400000200000200****",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E00000200000300****",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "1000000200000300****",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]