Dela via

Deklarationssats för frågeparametrar

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

Frågor som skickas till Kusto kan innehålla en uppsättning namn- eller värdepar. The pairs are called query parameters, together with the query text itself. Frågan kan referera till ett eller flera värden genom att ange namn och typ i en deklarationsuttryck för frågeparametrar.

Frågeparametrar har två huvudsakliga användningsområden:

  • Som en skyddsmekanism mot inmatningsattacker.
  • Som ett sätt att parametrisera frågor.

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.

Deklarera frågeparametrar

Om du vill referera till frågeparametrar måste frågetexten eller funktionerna den använder först deklarera vilken frågeparameter den använder. För varje parameter innehåller deklarationen namn och skalär typ. Parametern kan också ha ett standardvärde. Standardvärdet används om begäran inte ger något konkret värde för parametern. Kusto parsar sedan frågeparameterns värde enligt dess normala parsningsregler för den typen.

Syntax

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

Learn more about syntax conventions.

Parameters

Name Type Required Description
Name1 string ✔️ Namnet på en frågeparameter som används i frågan.
Type1 string ✔️ Motsvarande typ, till exempel string eller datetime. Värdena som tillhandahålls av användaren kodas som strängar. Lämplig parsningsmetod tillämpas på frågeparametern för att få ett starkt skrivet värde.
DefaultValue1 string Ett standardvärde för parametern. Det här värdet måste vara en literal av lämplig skalartyp.

Note

  • Precis som användardefinierade funktionerkan frågeparametrar av typen dynamic inte ha standardvärden.
  • Let, set och tabular-instruktioner är sammanspända/avgränsade med ett semikolon, annars betraktas de inte som en del av samma fråga.

Example

Exemplen i det här avsnittet visar hur du använder syntaxen för att komma igång.

The examples in this article use publicly available tables in the help cluster, such as the StormEvents table in the Samples database.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Du kan behöva ändra tabellnamnet i exempelfrågan för att matcha tabellen på din arbetsyta.

Deklarera frågeparametrar

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.

Kör frågan

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

Ange frågeparametrar i ett klientprogram

Namn och värden för frågeparametrar anges som string värden av programmet som gör frågan. Inget namn får upprepas.

Tolkningen av värdena görs enligt deklarationssatsen för frågeparametrar. Varje värde parsas som om det vore en literal i en frågas brödtext. Parsningen görs enligt den typ som anges av deklarationssatsen för frågeparametrar.

REST API

Frågeparametrar tillhandahålls av klientprogram via properties plats för begärandetextens JSON-objekt i en kapslad egenskapsväska med namnet Parameters. Här är till exempel brödtexten i ett REST API-anrop till Kusto som beräknar ålder för en viss användare, förmodligen genom att programmet ber om användarens födelsedag.

{
    "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).