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

Artículo
01/10/2024

Las consultas enviadas a Kusto pueden incluir un conjunto de pares 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.

Syntax

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

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

Parámetros

Nombre	Tipo	Requerido	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 agrupan 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

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

La aplicación que realiza la consulta proporciona los nombres y 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.

API REST

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 anidados 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).

Esta funcionalidad no se admite en Azure Monitor.

Share via