Instrucción de declaración de parámetros de consulta

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Las consultas enviadas a Kusto pueden incluir un conjunto de pares de nombre o valor. Los pares se denominan parámetros de consulta, junto con el propio texto de la consulta. La consulta puede hacer referencia a uno o varios valores, especificando nombres y tipo, en una instrucción de declaración de parámetros de consulta.

Los parámetros de consulta tienen dos usos principales:

• Como mecanismo de protección contra ataques por inyección.
• Como forma de parametrizar consultas.

En concreto, las aplicaciones cliente que combinan la entrada proporcionada por el usuario en las consultas que envían a Kusto deben usar el mecanismo para protegerse contra el equivalente kusto de ataques por inyección de CÓDIGO SQL.

Declaración de parámetros de consulta

Para hacer referencia a parámetros de consulta, el texto de la consulta o las funciones que usa, primero debe declarar qué parámetro de consulta usa. Para cada parámetro, la declaración proporciona el nombre y el tipo escalar. Opcionalmente, el parámetro también puede tener un valor predeterminado. El valor predeterminado se usa si la solicitud no proporciona un valor concreto para el parámetro . A continuación, Kusto analiza el valor del parámetro de consulta, según sus reglas de análisis normales para ese tipo.

Sintaxis

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

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Type	Obligatorio	Descripción
Nombre1	string	✔️	Nombre de un parámetro de consulta usado en la consulta.
Type1	string	✔️	Tipo correspondiente, como string o datetime. Los valores proporcionados por el usuario se codifican como cadenas. El método de análisis adecuado se aplica al parámetro de consulta para obtener un valor fuertemente tipado.
DefaultValue1	string		Valor predeterminado para el parámetro . Este valor debe ser un literal del tipo escalar adecuado.

Nota:

• Al igual que las funciones definidas por el usuario, los parámetros de consulta de tipo dynamic no pueden tener valores predeterminados.
• Las instrucciones let, set y tabular se unen o separan por punto y coma; de lo contrario, no se considerarán parte de la misma consulta.

Ejemplo

Ejecución de la consulta

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

Salida

EpisodeId	EventType	totalInjuries
12459	Clima de invierno	137
10477	Calor excesivo	200
10391	Heat (Calor)	187
10217	Calor excesivo	422
10217	Calor excesivo	519

Especificación de parámetros de consulta en una aplicación cliente

La aplicación proporciona los nombres y los valores de los parámetros de consulta como string valores. No se puede repetir ningún nombre.

La interpretación de los valores se realiza según la instrucción de declaración de parámetros de consulta. Cada valor se analiza como si fuera un literal en el cuerpo de una consulta. El análisis se realiza según el tipo especificado por la instrucción de declaración de parámetros de consulta.

REST API

Las aplicaciones cliente proporcionan parámetros de consulta a través de la properties ranura del objeto JSON del cuerpo de la solicitud, en un contenedor de propiedades anidadas denominado Parameters. Por ejemplo, este es el cuerpo de una llamada api rest a Kusto que calcula la edad de algún usuario, presumiblemente haciendo que la aplicación solicite el cumpleaños del usuario.

{
    "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 de Kusto

Para obtener información sobre cómo proporcionar los nombres y los valores de los parámetros de consulta al usar bibliotecas cliente de Kusto, consulte Uso de parámetros de consulta para proteger la entrada del usuario.

Kusto.Explorer

Para establecer los parámetros de consulta enviados al realizar una solicitud al servicio, use el icono "llave" de parámetros de consulta (ALT + P).