Istruzione di dichiarazione dei parametri di query

Articolo
11/23/2024

Si applica a: ✅Microsoft Fabric ✅Azure Esplora dati ✅ Azure Monitor✅Microsoft Sentinel

Le query inviate a Kusto possono includere un set di coppie nome o valore. Le coppie sono denominate parametri di query, insieme al testo della query stesso. 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 particolare, le applicazioni client che combinano l'input fornito dall'utente nelle query inviate a Kusto devono usare il meccanismo per proteggersi dagli attacchi Kusto equivalenti di attacchi SQL Injection .

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.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Digita	Obbligatorio	Descrizione
Nome1	`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.

Nota

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.

Esempio

Eseguire la query

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

Output

EpisodeId	EventType	totalInjuries
12459	Clima invernale	137
10477	Calore eccessivo	200
10391	Colpo	187
10217	Calore eccessivo	422
10217	Calore eccessivo	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++'])\"}}"
}

SDK Kusto

Per informazioni su come specificare i nomi e i valori dei parametri di query quando si usano le librerie client Kusto, vedere Usare i parametri di query per proteggere l'input dell'utente.

Kusto.Explorer

Per impostare i parametri di query inviati quando si effettua una richiesta al servizio, usare l'icona "wrench" dei parametri di query ( + ALTP).

Condividi tramite