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

Les requêtes envoyées à Kusto peuvent inclure un ensemble de paires nom/valeur. Les paires sont appelées paramètres de requête, ainsi que le texte de la requête lui-même. 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 main :

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

En particulier, les applications clientes qui combinent des entrées fournies par l’utilisateur dans des requêtes qu’elles envoient ensuite à Kusto doivent utiliser le mécanisme pour se protéger contre l’équivalent Kusto des attaques par injection de code SQL .

Déclaration de paramètres de requête

Pour référencer des paramètres de requête, le texte de la requête, ou les fonctions qu’elle utilise, doivent 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

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

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
Nom1	string	✔️	Nom d’un paramètre de requête utilisé dans la requête.
Type1	string	✔️	Type correspondant, par string exemple 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 du paramètre . Cette valeur doit être un littéral du type scalaire approprié.

Notes

• 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.
• Les instructions Let, set et tabulaires sont regroupées/séparées par un point-virgule, sinon elles ne sont pas considérées comme faisant partie de la même requête.

Exemple

Exécuter la requête

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

Sortie

EpisodeId	Type d’événement	totalInjuries
12459	Météo hivernale	137
10477	Chaleur excessive	200
10391	Chauffage	187
10217	Chaleur excessive	422
10217	Chaleur excessive	519

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

Les noms et les valeurs des paramètres de requête sont fournis en tant que string valeurs par l’application qui effectue 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 selon le type spécifié par l’instruction de déclaration des paramètres de requête.

API REST

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

Kits SDK Kusto

Pour savoir comment fournir les noms et les valeurs des paramètres de requête lors de l’utilisation de bibliothèques clientes Kusto, consultez Utiliser des paramètres de requête pour protéger les entrées utilisateur.

Kusto.Explorer

Pour définir les paramètres de requête envoyés lors de l’envoi d’une demande au service, utilisez l’icône « wrench » des paramètres de requête (ALT + P).

Cette fonctionnalité n’est pas prise en charge dans Azure Monitor.