Příkaz deklarace parametrů dotazu

Článek
11/23/2024

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer ✅Azure Monitor✅Microsoft Sentinel

Dotazy odeslané do Kusto můžou obsahovat sadu dvojic názvů nebo hodnot. Dvojice se nazývají parametry dotazu společně se samotným textem dotazu. Dotaz může odkazovat na jednu nebo více hodnot zadáním názvů a typů v příkazu deklarace parametrů dotazu.

Parametry dotazu mají dvě hlavní použití:

Jako ochranný mechanismus proti útokům prostřednictvím injektáže.
Jako způsob parametrizace dotazů.

Zejména klientské aplikace, které kombinují vstupy poskytované uživatelem v dotazech, které pak posílají do Kusto, by měly použít mechanismus k ochraně před ekvivalentem útoků Prostřednictvím injektáže SQL.

Deklarování parametrů dotazu

Pokud chcete odkazovat na parametry dotazu, text dotazu nebo funkce, které používá, musí nejprve deklarovat, který parametr dotazu používá. Pro každý parametr poskytuje deklarace název a skalární typ. Volitelně může mít parametr také výchozí hodnotu. Výchozí hodnota se použije v případě, že požadavek neposkytuje konkrétní hodnotu parametru. Kusto pak parsuje hodnotu parametru dotazu podle normálních pravidel analýzy daného typu.

Syntaxe

declarequery_parameters ( Name1 : Type1 [= DefaultValue1] [,...]);

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Type	Požadováno	Popis
Název 1	`string`	✔️	Název parametru dotazu použitého v dotazu.
Typ 1	`string`	✔️	Odpovídající typ, například `string` nebo `datetime`. Hodnoty poskytnuté uživatelem jsou kódovány jako řetězce. Pro parametr dotazu se použije příslušná metoda analýzy, která získá hodnotu silného typu.
DefaultValue1	`string`		Výchozí hodnota parametru. Tato hodnota musí být literálem příslušného skalárního typu.

Poznámka:

Stejně jako uživatelem definované funkce nemohou parametry dotazu typu dynamic obsahovat výchozí hodnoty.
Příkazy Let, set a tabulkové příkazy jsou provázané dohromady nebo oddělené středníkem, jinak se nepovažují za součást stejného dotazu.

Příklad

Spuštění dotazu

declare query_parameters(maxInjured:long = 90);
StormEvents 
| where InjuriesDirect + InjuriesIndirect > maxInjured
| project EpisodeId, EventType, totalInjuries = InjuriesDirect + InjuriesIndirect

Výstup

EpisodeId	Typ události	totalInjuries
12459	Počasí v zimě	137
10477	Nadměrné teplo	200
10391	Heat	187
10217	Nadměrné teplo	422
10217	Nadměrné teplo	519

Zadání parametrů dotazu v klientské aplikaci

Názvy a hodnoty parametrů dotazu jsou poskytovány jako string hodnoty aplikace, která dotaz vytváří. Nesmí se opakovat žádný název.

Interpretace hodnot se provádí podle příkazu deklarace parametrů dotazu. Každá hodnota se analyzuje, jako by šlo o literál v těle dotazu. Analýza se provádí podle typu určeného příkazem deklarace parametrů dotazu.

REST API

Parametry dotazu poskytují klientské aplikace prostřednictvím properties slotu objektu JSON v těle požadavku v vnořeném kontejneru vlastností s názvem Parameters. Tady je například tělo volání rozhraní REST API kusto, které počítá věk některých uživatelů, pravděpodobně tím, že aplikace požádá o narozeniny uživatele.

{
    "ns": null,
    "db": "myDB",
    "csl": "declare query_parameters(birthday:datetime); print strcat(\"Your age is: \", tostring(now() - birthday))",
    "properties": "{\"Options\":{},\"Parameters\":{\"birthday\":\"datetime(1970-05-11)\",\"courses\":\"dynamic(['Java', 'C++'])\"}}"
}

Sady Kusto SDK

Informace o tom, jak zadat názvy a hodnoty parametrů dotazu při použití klientských knihoven Kusto, najdete v tématu Použití parametrů dotazu k ochraně uživatelského vstupu.

Kusto.Explorer

Pokud chcete nastavit parametry dotazu odeslané při vytváření požadavku do služby, použijte ikonu parametry dotazu "klíč" (PALT + ).

Sdílet prostřednictvím