Compartir a través de

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

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

Las consultas enviadas a Kusto pueden incluir un conjunto de pares de nombre o valor. The pairs are called query parameters, together with the query text itself. 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.

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.

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

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

Learn more about syntax conventions.

Parameters

Name Type Required Description
Name1 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.

Note

  • 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.

Example

Los ejemplos de esta sección muestran cómo usar la sintaxis para ayudarle a empezar.

The examples in this article use publicly available tables in the help cluster, such as the StormEvents table in the Samples database.

The examples in this article use publicly available tables, such as the Weather table in the Weather analytics sample gallery. Es posible que tenga que modificar el nombre de la tabla en la consulta de ejemplo para que coincida con la tabla del área de trabajo.

Declarar parámetros de consulta

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.

Ejecución de la consulta

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

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++'])\"}}"
}

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

  • Last updated on