Příkaz deklarace parametrů dotazu

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Dotazy odeslané do Kusto můžou obsahovat sadu dvojic názvů nebo hodnot. The pairs are called query parameters, together with the query text itself. 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ů.

In particular, client applications that combine user-provided input in queries that they then send to Kusto should use the mechanism to protect against the Kusto equivalent of SQL Injection attacks.

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.

Syntax

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

Learn more about syntax conventions.

Parameters

Name	Typ	Required	Description
Name1	string	✔️	Název parametru dotazu použitého v dotazu.
Type1	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.

Note

• 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.

Example

Příklady v této části ukazují, jak používat syntaxi, která vám pomůže začít.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Možná budete muset změnit název tabulky v ukázkovém dotazu tak, aby odpovídal tabulce v pracovním prostoru.

Deklarace parametrů dotazu

This query retrieves storm events from the StormEvents table where the total number of direct and indirect injuries exceeds a specified threshold (default is 90). It then projects the EpisodeId, EventType, and the total number of injuries for each of these events.

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

Output

EpisodeId	EventType	totalInjuries
12459	Winter Weather	137
10477	Excessive Heat	200
10391	Heat	187
10217	Excessive Heat	422
10217	Excessive Heat	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++'])\"}}"
}

Kusto SDKs

To learn how to provide the names and values of query parameters when using Kusto client libraries, see Use query parameters to protect user input.

Kusto.Explorer

To set the query parameters sent when making a request to the service, use the Query parameters "wrench" icon (ALT + P).