Istruzione di dichiarazione dei parametri di query

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

Le query inviate a Kusto possono includere un set di coppie nome o valore. The pairs are called query parameters, together with the query text itself. La query può fare riferimento a uno o più valori, specificando nomi e tipo, in un'istruzione di dichiarazione di parametri di query.

I parametri di query hanno due usi principali:

• Come meccanismo di protezione dagli attacchi injection.
• Come modo per parametrizzare le query.

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.

Dichiarazione di parametri di query

Per fare riferimento ai parametri di query, il testo della query o le funzioni usate deve innanzitutto dichiarare il parametro di query usato. Per ogni parametro, la dichiarazione fornisce il nome e il tipo scalare. Facoltativamente, il parametro può anche avere un valore predefinito. Il valore predefinito viene usato se la richiesta non fornisce un valore concreto per il parametro . Kusto analizza quindi il valore del parametro di query, in base alle normali regole di analisi per quel tipo.

Syntax

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

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
Name1	string	✔️	Nome di un parametro di query utilizzato nella query.
Type1	string	✔️	Tipo corrispondente, ad esempio string o datetime. I valori forniti dall'utente vengono codificati come stringhe. Il metodo di analisi appropriato viene applicato al parametro di query per ottenere un valore fortemente tipizzato.
DefaultValue1	string		Valore predefinito per il parametro . Questo valore deve essere un valore letterale del tipo scalare appropriato.

Note

• Analogamente alle funzioni definite dall'utente, i parametri di query di tipo dynamic non possono avere valori predefiniti.
• Le istruzioni let, set e tabulari vengono unite/separate da un punto e virgola, altrimenti non verranno considerate parte della stessa query.

Example

Negli esempi di questa sezione viene illustrato come usare la sintassi per iniziare.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Potrebbe essere necessario modificare il nome della tabella nella query di esempio in modo che corrisponda alla tabella nell'area di lavoro.

Dichiarare i parametri di query

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

Specificare i parametri di query in un'applicazione client

I nomi e i valori dei parametri di query vengono forniti come string valori dall'applicazione che effettua la query. Nessun nome può ripetersi.

L'interpretazione dei valori viene eseguita in base all'istruzione di dichiarazione dei parametri di query. Ogni valore viene analizzato come se fosse un valore letterale nel corpo di una query. L'analisi viene eseguita in base al tipo specificato dall'istruzione di dichiarazione dei parametri di query.

REST API

I parametri di query vengono forniti dalle applicazioni client tramite lo properties slot dell'oggetto JSON del corpo della richiesta, in un contenitore di proprietà annidato denominato Parameters. Ad esempio, ecco il corpo di una chiamata API REST a Kusto che calcola l'età di un utente, presumibilmente facendo in modo che l'applicazione richieda il compleanno dell'utente.

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