Pattern, instruction

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. Deux instructions doivent être séparées 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 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.

Syntaxe

• Déclarez un modèle vide :

  declarepattern PatternName ;

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

  declarepattern 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

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.

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

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

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

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 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 prévoit plutôt d’exploiter 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 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 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 à 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.10) a été passée au modèle. Il précède donc la requête de l’utilisateur avec 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.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")

Sortie