Partager via

Conventions de syntaxe pour la documentation de référence

Changer de service à l’aide de la liste déroulante Version . En savoir plus sur la navigation.
S’applique à : ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Cet article décrit les conventions de syntaxe suivies dans la documentation de référence sur le langage de requête Kusto (KQL) et les commandes de gestion .

Un bon endroit pour commencer à apprendre le langage de requête Kusto consiste à comprendre la structure de requête globale. La première chose que vous remarquez lorsque vous examinez une requête Kusto est l’utilisation du symbole de canal (|). La structure d’une requête Kusto commence par obtenir vos données à partir d’une source de données, puis en passant les données dans un pipeline, et chaque étape fournit un certain niveau de traitement, puis transmet les données à l’étape suivante. À la fin du pipeline, vous obtenez votre résultat final. En effet, il s’agit de notre pipeline :

Get Data | Filter | Summarize | Sort | Select

Ce concept de passage de données vers le bas du pipeline permet une structure intuitive, car il est facile de créer une image mentale de vos données à chaque étape.

Pour illustrer cela, examinons la requête suivante, qui examine les journaux de connexion Microsoft Entra. Lorsque vous lisez chaque ligne, vous pouvez voir les mots clés qui indiquent ce qui se passe aux données. Nous avons inclus la phase pertinente dans le pipeline en tant que commentaire dans chaque ligne.

Note

Vous pouvez ajouter des commentaires à n’importe quelle ligne d’une requête en les précédant avec une double barre oblique (//).

SigninLogs                              // Get data
| evaluate bag_unpack(LocationDetails)  // Ignore this line for now; we'll come back to it at the end.
| where RiskLevelDuringSignIn == 'none' // Filter
   and TimeGenerated >= ago(7d)         // Filter
| summarize Count = count() by city     // Summarize
| sort by Count desc                    // Sort
| take 5                                // Select

Étant donné que la sortie de chaque étape sert d’entrée pour l’étape suivante, l’ordre des étapes peut déterminer les résultats de la requête et affecter ses performances. Il est essentiel que vous commandez les étapes en fonction de ce que vous souhaitez extraire de la requête.

Conseil / Astuce

  • Une bonne règle de pouce consiste à filtrer vos données tôt, de sorte que vous transmettez uniquement les données pertinentes vers le bas du pipeline. Cela augmente considérablement les performances et garantit que vous n’incluez pas accidentellement les données non pertinentes dans les étapes de synthèse.
  • Cet article décrit d’autres meilleures pratiques à garder à l’esprit. Pour obtenir une liste plus complète, consultez les meilleures pratiques de requête.

Conventions de syntaxe

Convention Descriptif
Block Littéraux de chaîne à entrer exactement comme indiqué.
Italic Paramètres à fournir une valeur lors de l’utilisation de la fonction ou de la commande.
[ ] Indique que l’élément entouré est facultatif.
( ) Indique qu’au moins l’un des éléments placés entre eux est requis.
| (canal) Utilisé entre crochets ou crochets pour indiquer que vous pouvez spécifier l’un des éléments séparés par le caractère de canal. Dans ce formulaire, le canal équivaut à l’opérateur OR logique. Dans un bloc (|), le canal fait partie de la syntaxe de requête KQL.
[, ...] Indique que le paramètre précédent peut être répété plusieurs fois, séparés par des virgules.
; Fin de l’instruction de requête.

Examples

Fonction scalaire

Cet exemple montre la syntaxe et un exemple d’utilisation de la fonction de hachage, suivi d’une explication de la façon dont chaque composant de syntaxe se traduit par l’exemple d’utilisation.

Syntaxe

hash( source [,mod])

Exemple d’utilisation

hash("World")
  • Le nom de la fonction, hashet la parenthèse ouvrante sont entrées exactement comme indiqué.
  • « World » est passé en tant qu’argument pour le paramètre source requis.
  • Aucun argument n’est passé pour le paramètre mod , qui est facultatif comme indiqué par les crochets.
  • La parenthèse fermante est entrée exactement comme indiqué.

Opérateur tabulaire

Cet exemple montre la syntaxe et un exemple d’utilisation de l’opérateur de tri, suivi d’une explication de la façon dont chaque composant de syntaxe se traduit par l’exemple d’utilisation.

Syntaxe

T| sort bycolumn [] [asc | descnulls first | nulls last] [] [, ...]

Exemple d’utilisation

StormEvents
| sort by State asc, StartTime desc
  • La table StormEvents est passée en tant qu’argument pour le paramètre T requis.
  • | sort by est entré exactement comme indiqué. Dans ce cas, le caractère de canal fait partie de la syntaxe de l’instruction d’expression tabulaire , comme représenté par le texte de bloc. Pour plus d’informations, consultez Qu’est-ce qu’une instruction de requête.
  • La colonne State est passée en tant qu’argument pour le paramètre de colonne requis avec l’indicateur facultatif asc .
  • Après une virgule, un autre ensemble d’arguments est passé : la colonne StartTime avec l’indicateur facultatif desc . La syntaxe [, ...] indique que d’autres jeux d’arguments peuvent être passés, mais ne sont pas obligatoires.

Utilisation de paramètres facultatifs

Pour fournir un argument pour un paramètre facultatif qui vient après un autre paramètre facultatif, vous devez fournir un argument pour le paramètre précédent. Cette exigence est due au fait que les arguments doivent suivre l’ordre spécifié dans la syntaxe. Si vous n’avez pas de valeur spécifique à passer pour le paramètre, utilisez une valeur vide du même type.

Exemple de paramètres facultatifs séquentiels

Tenez compte de la syntaxe du plug-in http_request :

evaluate http_request ( Uri [,RequestHeaders [,Options]] )

RequestHeaders et Options sont des paramètres facultatifs de type dynamique. Pour fournir un argument pour le paramètre Options , vous devez également fournir un argument pour le paramètre RequestHeaders . L’exemple suivant montre comment fournir une valeur vide pour le premier paramètre facultatif , RequestHeaders, afin de pouvoir spécifier une valeur pour le deuxième paramètre facultatif, Options.

evaluate http_request ( "https://contoso.com/", dynamic({}), dynamic({ EmployeeName: Nicole }) )

Contenu connexe

  • Last updated on