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

Article
07/04/2024

Les requêtes envoyées à Kusto peuvent inclure un ensemble de paires nom ou 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 principales :

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 l’entrée fournie par l’utilisateur dans les requêtes qu’elles envoient ensuite à Kusto doivent utiliser le mécanisme pour se protéger contre l’équivalent kusto des attaques par injection SQL.

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.

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom	Type	Requise	Description
Nom1	`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é.

Remarque

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.

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

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 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 de développement logiciel (SDK) Kusto

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

Kusto.Explorer

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

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

Partager via