Příkaz deklarace parametrů dotazu
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] [,...]);
Parametry
| Název | Typ | Vyžadováno | Popis |
|---|---|---|---|
| Název1 | řetězec | ✓ | Název parametru dotazu použitého v dotazu. |
| Typ1 | řetězec | ✓ | 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 | řetězec | 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
dynamicvý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
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++'])\"}}"
}
Kusto .NET SDK
Pokud chcete zadat názvy a hodnoty parametrů dotazu při použití klientské knihovny Kusto .NET, jeden vytvoří novou instanci objektu ClientRequestProperties a pak použije HasParametermetody , SetParametera ClearParameter k manipulaci s parametry dotazu. Tato třída poskytuje řadu přetížení silného typu pro SetParameter; interně vygenerují odpovídající literál dotazovacího jazyka a odesílají ho prostřednictvím string rozhraní REST API, jak je popsáno výše. Samotný text dotazu musí parametry dotazu deklarovat.
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á.