Příkaz deklarace parametrů dotazu

  • Článek

Dotazy odeslané do Kusto můžou obsahovat sadu dvojic názvů a 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ů.

Konkrétně klientské aplikace, které kombinují vstupy poskytnuté uživatelem v dotazech, které pak odešlou do Kusto, by měly používat mechanismus ochrany před útoky pomocí injektáže SQL kusto.

Deklarování parametrů dotazu

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

Syntax

declarequery_parameters(Název1:Type1 [=DefaultValue1] [,...] );

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

Parametry

Název Typ Vyžadováno Popis
Název1 string ✔️ Název parametru dotazu použitého v dotazu.
Typ1 string ✔️ Odpovídající typ, například string nebo datetime. Hodnoty zadané uživatelem jsou zakódovány jako řetězce. Na parametr dotazu se použije příslušná metoda analýzy, aby se získala hodnota silného typu.
Výchozí hodnota1 string Výchozí hodnota parametru. Tato hodnota musí být literálem příslušného skalárního typu.

Poznámka

  • Podobně jako uživatelem definované funkce nemohou mít parametry dotazu typu dynamic výchozí hodnoty.
  • Příkazy Let, set a tabulkové příkazy jsou spojeny dohromady nebo oddělené středníkem, jinak nebudou považovány 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

Id epizody Typ události totalInjuries
12459 Zimní počasí 137
10477 Nadměrné teplo 200
10391 Tepla 187
10217 Nadměrné teplo 422
10217 Nadměrné teplo 519

Určení parametrů dotazu v klientské aplikaci

Názvy a hodnoty parametrů dotazu jsou poskytovány jako string hodnoty aplikací, která dotaz provádí. Nesmí se opakovat žádné jméno.

Interpretace hodnot se provádí podle příkazu deklarace parametrů dotazu. Každá hodnota se analyzuje, jako by se jednalo o literál v textu 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 slotu properties objektu JSON v těle požadavku ve vnořeném sáčku vlastností s názvem Parameters. Tady je například tělo volání rozhraní REST API kusto, které vypočítá věk některého uživatele, pravděpodobně tak, ž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 SDK Kusto

Informace o tom, jak zadat názvy a hodnoty parametrů dotazu při používání klientských knihoven Kusto, najdete v tématu Ochrana vstupu uživatele pomocí parametrů dotazu.

Kusto.Explorer

Pokud chcete nastavit parametry dotazu odesílané při vytváření požadavku na službu, použijte ikonu "klíč" parametrů dotazu (ALT + P).

Tato funkce není ve službě Azure Monitor podporovaná.