Partager via

Instruction de déclaration des paramètres de requête

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

Les requêtes envoyées à Kusto peuvent inclure un ensemble de paires nom ou valeur. The pairs are called query parameters, together with the query text itself. La requête peut référencer une ou plusieurs valeurs, en spécifiant des noms et un type, dans une instruction de déclaration de paramètres de requête.

Les paramètres de requête ont deux utilisations principales :

  • En tant que mécanisme de protection contre les attaques par injection.
  • Pour paramétrer des requêtes.

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.

Déclaration des paramètres de requête

Pour référencer les paramètres de requête, le texte de la requête ou les fonctions qu’il utilise doit d’abord déclarer le paramètre de requête qu’il utilise. Pour chaque paramètre, la déclaration fournit le nom et le type scalaire. Si vous le souhaitez, le paramètre peut également avoir une valeur par défaut. La valeur par défaut est utilisée si la requête ne fournit pas de valeur concrète pour le paramètre. Kusto analyse ensuite la valeur du paramètre de requête, en fonction de ses règles d’analyse normales pour ce type.

Syntax

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

Learn more about syntax conventions.

Parameters

Name Type Required Description
Name1 string ✔️ Nom d’un paramètre de requête utilisé dans la requête.
Type1 string ✔️ Type correspondant, tel que string ou datetime. Les valeurs fournies par l’utilisateur sont encodées sous forme de chaînes. La méthode d’analyse appropriée est appliquée au paramètre de requête pour obtenir une valeur fortement typée.
DefaultValue1 string Valeur par défaut pour le paramètre. Cette valeur doit être un littéral du type scalaire approprié.

Note

  • Comme les fonctions définies par l’utilisateur, les paramètres de requête de type dynamic ne peuvent pas avoir de valeurs par défaut.
  • Supposons que les instructions tabulaires et set soient regroupées/séparées par un point-virgule, sinon elles ne seront pas considérées comme faisant partie de la même requête.

Example

Les exemples de cette section montrent comment utiliser la syntaxe pour vous aider à commencer.

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. Vous devrez peut-être modifier le nom de la table dans l’exemple de requête pour qu’elle corresponde à la table de votre espace de travail.

Déclarer les paramètres de requête

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.

Exécuter la requête

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

Spécifier des paramètres de requête dans une application cliente

Les noms et valeurs des paramètres de requête sont fournis en tant que string valeurs par l’application effectuant la requête. Aucun nom ne peut se répéter.

L’interprétation des valeurs est effectuée en fonction de l’instruction de déclaration des paramètres de requête. Chaque valeur est analysée comme s’il s’agissait d’un littéral dans le corps d’une requête. L’analyse est effectuée en fonction du type spécifié par l’instruction de déclaration des paramètres de requête.

REST API

Les paramètres de requête sont fournis par les applications clientes via l’emplacement properties de l’objet JSON du corps de la requête, dans un conteneur de propriétés imbriqué appelé Parameters. Par exemple, voici le corps d’un appel d’API REST à Kusto qui calcule l’âge d’un utilisateur, probablement en demandant à l’application l’anniversaire de l’utilisateur.

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