Istruzione di dichiarazione dei parametri di query

  • Articolo

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 dei parametri di query.

I parametri di query hanno due usi principali:

  • Meccanismo di protezione da attacchi di inserimento.
  • Come modo per parametrizzare le query.

In particolare, le applicazioni client che combinano l'input fornito dall'utente nelle query che quindi inviano a Kusto devono usare il meccanismo per proteggere 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 prima dichiarare il parametro di query usato. Per ogni parametro, la dichiarazione fornisce il nome e il tipo scalare. Facoltativamente, il parametro può avere anche 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 regole di analisi normali per tale tipo.

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
Nome1 string ✔️ Nome di un parametro di query usato 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

  • Come le funzioni definite dall'utente, i parametri di query di tipo dynamic non possono avere valori predefiniti.
  • Le istruzioni let, set e tabulari vengono raggruppate/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

EpisodioId EventType totalInjuries
12459 Meteo invernale 137
10477 Calore eccessivo 200
10391 Calore 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 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 dichiarazione dei parametri di query.

API REST

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 con la richiesta dell'applicazione per 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 fornire 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 utente.

Kusto.Explorer

Per impostare i parametri di query inviati durante l'esecuzione di una richiesta al servizio, usare l'icona "wrench" dei parametri di query (ALT + P).

Questa funzionalità non è supportata in Monitoraggio di Azure