Pattern, instruction

Un modèle est une construction qui mappe des tuples de chaîne à des 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. Deux instructions doivent être séparées par un point-virgule.

Les modèles vides sont des modèles qui sont déclarés, mais qui ne définissent pas de mappage. Lorsqu’ils sont appelés, ils retournent des SEM0036 d’erreur 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 de Langage de requête Kusto (KQL) peuvent utiliser les détails retournés dans le cadre de leur processus pour enrichir les résultats des requêtes KQL. Pour plus d’informations, consultez Utilisation d’applications de niveau intermédiaire.

Syntax

• Déclarez un modèle vide :

  declarepatternPatternName;

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

  declarepatternPatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

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

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

  } ;

• Appelez un modèle :

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

Découvrez 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 path. Les modèles ne peuvent avoir aucun chemin ou un seul chemin.
PathArgType	string		Type de l’argument PathArgType . Valeurs possibles : string
ArgValue	string	✔️	Valeurs de tuple ArgName et pathName facultatives à 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

Dans chacun des exemples suivants, un modèle est déclaré, défini, puis appelé.

Définir des modèles simples

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

Exécuter la requête

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

Sortie

Capital
Edmonton

Exécuter la requête

L’exemple suivant définit un modèle qui définit certaines données d’application délimité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

Sortie

Application	Données	Mesures
Application n°2	9
Application n°2	8
Application n°2	7
Application n°2	6
Application n°2	5
Application n°1		0.53674122855537532
Application n°1		0.78304713305654439
Application n°1		0.20168860732346555
Application n°1		0.13249123867679469
Application n°1		0.19388305330563443

Normalisation

Il existe des variantes de syntaxe pour appeler des modèles. Par exemple, l’union suivante retourne une seule expression de modèle, 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 accordé aux caractères génériques dans un modèle. Par exemple, la requête suivante retourne un seul appel de modèle manquant.

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

Retourne une erreur sémantique

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 offre à 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 de son service interne.

À cette fin, l’application fournit aux utilisateurs une instruction de modèle 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 prévoit plutôt de tirer parti de l’erreur retournée par un modèle vide pour récupérer les clés dont elle a besoin. Il ajoute donc la requête à 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ère une nouvelle déclaration qui définit le mappage de données d’enrichissement approprié. Enfin, l’application ajoute la nouvelle définition à la requête de l’utilisateur, la renvoie pour traitement et retourne le résultat qu’elle reçoit à l’utilisateur.

Exemple

Dans l’exemple suivant, une application de niveau intermédiaire permet d’enrichir les requêtes avec des emplacements de longitude/latitude. L’application utilise un service interne pour mapper des adresses IP à des emplacements de longitude/latitude et fournit un modèle appelé map_ip_to_longlat à cet effet. Supposons que l’application obtient la requête suivante de l’utilisateur :

map_ip_to_longlat("10.10.10.10")

L’application n’analyse pas cette requête et ne sait donc pas quelle adresse IP (10.10.10.10) a été passée au modèle. Il ajoute donc la requête utilisateur à une déclaration de modèle vide map_ip_to_longlat et l’envoie pour 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')"]

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

Exécuter la requête

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

Sortie

Lat	Long
37.405992	-122.078515

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