Instruction Pattern

S’applique à : ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Un modèle est une construction qui mappe des tuples de chaîne aux expressions tabulaires.

Chaque modèle doit déclarer un nom de modèle et éventuellement définir un mappage de modèle. Les modèles qui définissent un mappage retournent une expression tabulaire lorsqu’ils sont appelés. Séparez les deux instructions par un point-virgule.

Les modèles vides sont des modèles déclarés, mais qui ne définissent pas de mappage. Lorsqu’elles sont appelées, elles retournent une erreur SEM0036 ainsi que les détails des définitions de modèle manquantes dans l’en-tête HTTP.

Les applications de niveau intermédiaire qui fournissent une expérience KQL (Kusto Query Language) peuvent utiliser les détails retournés dans le cadre de leur processus pour enrichir les résultats de requête KQL. Pour plus d’informations, consultez Utilisation d’applications de niveau intermédiaire.

Syntaxe

• Déclarez un modèle vide :

  declare pattern PatternName;

• Déclarez et définissez un modèle :

  declare pattern PatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expression1};

      [ (ArgValue1_2 [,ArgValue2_2, ... ] ) [ .[PathValue_2] ] ={expression2}; ... ]

  } ;

• Appeler un modèle :

  • PatternName(ArgValue1 [,ArgValue2 ...] ).PathValue
  • PatternName(ArgValue1 [,ArgValue2 ...] ).["PathValue"]

En savoir plus sur les conventions de syntaxe .

Paramètres

Nom	Type	Obligatoire	Description
PatternName	string	✔️	Nom du modèle.
ArgName	string	✔️	Nom de l’argument. Les modèles peuvent avoir un ou plusieurs arguments.
ArgType	string	✔️	Type de données scalaire de l’argument ArgName . Valeurs possibles : string
PathName	string		Nom de l’argument chemin d’accès. Les modèles ne peuvent pas avoir de chemin d’accès ou un chemin d’accès.
PathArgType	string		Type de l’argument PathArgType. Valeurs possibles : string
ArgValue	string	✔️	Les valeurs de tuple ArgName et facultatives PathName à mapper à une expression .
PathValue	string		Valeur à mapper pour PathName.
expression	string	✔️	Expression tabulaire ou lambda qui fait référence à une fonction retournant des données tabulaires. Par exemple : Logs | where Timestamp > ago(1h)

Exemples

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

Les exemples de cet article utilisent des tables disponibles publiquement, telles que la table StormEvents dans l’analyse météo exemples de données.

Définir un modèle simple

Cet exemple définit un modèle qui mappe les états à une expression qui retourne sa capitale/ville principale.

declare pattern country = (name:string)[state:string]
{
  ("USA").["New York"] = { print Capital = "Albany" };
  ("USA").["Washington"] = { print Capital = "Olympia" };
  ("Canada").["Alberta"] = { print Capital = "Edmonton" };
};
country("Canada").Alberta

de sortie

Capital
Edmonton

Définir un modèle délimité

Cet exemple définit un modèle pour étendre les données et les métriques des données d’application. Le modèle est appelé pour retourner une union des données.

declare pattern App = (applicationId:string)[scope:string]
{
    ('a1').['Data']    = { range x from 1 to 5 step 1 | project App = "App #1", Data    = x };
    ('a1').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #1", Metrics = rand() };
    ('a2').['Data']    = { range x from 1 to 5 step 1 | project App = "App #2", Data    = 10 - x };
    ('a3').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #3", Metrics = rand() };
};
union App('a2').Data, App('a1').Metrics

de sortie

Appli	Données	Métrique
Application n° 2	9
Application n° 2	8
Application n° 2	7
Application n° 2	6
Application n° 2	5
Application #1		0.53674122855537532
Application #1		0.78304713305654439
Application #1		0.20168860732346555
Application #1		0.13249123867679469
Application #1		0.19388305330563443

Normalisation

Il existe des variantes de syntaxe pour appeler des modèles. Par exemple, l’union suivante retourne une expression de modèle unique, car tous les appels sont du même modèle.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union
  app("ApplicationX").StartEvents,
  app('ApplicationX').StartEvents,
  app("ApplicationX").['StartEvents'],
  app("ApplicationX").["StartEvents"]

Aucun caractère générique

Il n’y a pas de traitement spécial donné aux caractères génériques dans un modèle. Par exemple, la requête suivante retourne un appel de modèle manquant unique.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union app("ApplicationX").["*"]
| count

erreur sémantique de sortie

Une ou plusieurs références de modèle n’ont pas été déclarées. Références de modèle détectées : ["app('ApplicationX').[' *']"]

Utiliser des applications de niveau intermédiaire

Une application de niveau intermédiaire fournit à ses utilisateurs la possibilité d’utiliser KQL et souhaite améliorer l’expérience en enrichissant les résultats de la requête avec des données augmentées à partir de son service interne.

À cette fin, l’application fournit aux utilisateurs une instruction pattern qui retourne des données tabulaires que leurs utilisateurs peuvent utiliser dans leurs requêtes. Les arguments du modèle sont les clés que l’application utilisera pour récupérer les données d’enrichissement.

Lorsque l’utilisateur exécute la requête, l’application n’analyse pas la requête elle-même, mais utilise plutôt l’erreur retournée par un modèle vide pour récupérer les clés dont elle a besoin. Ainsi, il précède la requête avec la déclaration de modèle vide, l’envoie au cluster pour traitement, puis analyse l’en-tête HTTP retourné pour récupérer les valeurs des arguments de modèle manquants. L’application utilise ces valeurs pour rechercher les données d’enrichissement et générer une nouvelle déclaration qui définit le mappage approprié des données d’enrichissement.

Enfin, l’application ajoute la nouvelle définition à la requête, la renvoie pour traitement et retourne le résultat qu’elle reçoit à l’utilisateur.

Exemple

Dans les exemples, un modèle est déclaré, défini, puis appelé.

Déclarer un modèle vide

Dans cet exemple, une application de niveau intermédiaire enrichit les requêtes avec des emplacements longitude/latitude. L’application utilise un service interne pour mapper les adresses IP aux emplacements longitude/latitude, et fournit un modèle appelé map_ip_to_longlat. Lorsque la requête est exécutée, elle retourne une erreur avec des définitions de modèle manquantes :

map_ip_to_longlat("10.10.10.10")

Déclarer et définir un modèle

L’application n’analyse pas cette requête et ne sait donc pas quelle adresse IP (10.10.10.10.10) a été passée au modèle. Ainsi, il précède la requête utilisateur avec une déclaration de modèle map_ip_to_longlat vide et l’envoie pour le traitement :

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

L’application reçoit l’erreur suivante en réponse.

Une ou plusieurs références de modèle n’ont pas été déclarées. Références de modèle détectées : ["map_ip_to_longlat('10.10.10.10')"]

Appeler un modèle

L’application inspecte l’erreur, détermine que l’erreur indique une référence de modèle manquante et récupère l’adresse IP manquante (10.10.10.10). Il utilise l’adresse IP pour rechercher les données d’enrichissement dans son service interne et crée un nouveau modèle définissant le mappage de l’adresse IP aux données de longitude et de latitude correspondantes. Le nouveau modèle est ajouté à la requête de l’utilisateur et réexécuter.

Cette fois,la requête réussit, car les données d’enrichissement sont désormais déclarées dans la requête, et le résultat est envoyé à l’utilisateur.

declare pattern map_ip_to_longlat = (address:string)
{
  ("10.10.10.10") = { print Lat=37.405992, Long=-122.078515 };
};
map_ip_to_longlat("10.10.10.10")

de sortie

Lat	Long
37.405992	-122.078515