Freigeben über

Pattern-Anweisung

  • Artikel

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Ein Muster ist ein Konstrukt, das Zeichenfolgen-Tupeln tabellarischen Ausdrücken zuordnet.

Jedes Muster muss einen Musternamen deklarieren und optional eine Musterzuordnung definieren. Muster, die eine Zuordnung definieren, geben beim Aufrufen einen tabellarischen Ausdruck zurück. Trennen Sie zwei beliebige Anweisungen durch ein Semikolon.

Leere Muster sind Muster, die deklariert werden, aber keine Zuordnung definieren. Wenn sie aufgerufen werden, geben sie fehler SEM0036 zusammen mit den Details der fehlenden Musterdefinitionen im HTTP-Header zurück.

Middle-Tier-Anwendungen, die eine Kusto Query Language (KQL)-Erfahrung bereitstellen, können die zurückgegebenen Details als Teil ihres Prozesses verwenden, um KQL-Abfrageergebnisse zu erweitern. Weitere Informationen finden Sie unter Arbeiten mit Anwendungen auf mittlerer Ebene.

Syntax

  • Deklarieren Sie ein leeres Muster:

    declare pattern PatternName-;

  • Deklarieren und Definieren eines Musters:

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

    {

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

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

    } ;

  • Aufrufen eines Musters:

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Art Erforderlich Beschreibung
PatternName- string ✔️ Der Name des Musters.
ArgName- string ✔️ Der Name des Arguments. Muster können ein oder mehrere Argumente enthalten.
ArgType- string ✔️ Der skalare Datentyp des arguments ArgName. Mögliche Werte: string
PathName- string Der Name des Pfadarguments. Muster können keinen Pfad oder einen Pfad haben.
PathArgType- string Der Typ des arguments PathArgType. Mögliche Werte: string
ArgValue- string ✔️ Die ArgName und optionale PathName Tupelwerte, die einem Ausdruckzugeordnet werden sollen.
PathValue- string Der wert, der für PathNamezugeordnet werden soll.
Ausdruck string ✔️ Ein tabellarischer oder Lambda-Ausdruck, der auf eine Funktion verweist, die tabellarische Daten zurückgibt. Beispiel: Logs | where Timestamp > ago(1h)

Beispiele

Im hilfeclustergibt es eine Samples Datenbank mit einer StormEvents Tabelle.

In diesen Beispielen wird ein Muster definiert.

Definieren eines einfachen Musters

In diesem Beispiel wird ein Muster definiert, das Zustände einem Ausdruck zuordnet, der seine Hauptstadt/Hauptstadt zurückgibt.

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

Ausgabe-

Kapital
Edmonton

Definieren eines bereichsbezogenen Musters

In diesem Beispiel wird ein Muster zum Bereich von Daten und Metriken von Anwendungsdaten definiert. Das Muster wird aufgerufen, um eine Vereinigung der Daten zurückzugeben.

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

Ausgabe-

App Daten Metrik
App Nr. 2 9
App Nr. 2 8
App Nr. 2 7
App Nr. 2 6
App Nr. 2 5
App Nr. 1 0.53674122855537532
App Nr. 1 0.78304713305654439
App Nr. 1 0.20168860732346555
App Nr. 1 0.13249123867679469
App Nr. 1 0.19388305330563443

Normalisierung

Es gibt Syntaxvariationen für das Aufrufen von Mustern. Beispielsweise gibt die folgende Union einen einzelnen Musterausdruck zurück, da alle Aufrufe dasselbe Muster aufweisen.

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

Keine Wildcards

Es gibt keine spezielle Behandlung für Wildcards in einem Muster. Die folgende Abfrage gibt beispielsweise einen einzelnen fehlenden Musteraufruf zurück.

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

Ausgabesemantikfehler

Mindestens ein Musterverweise wurden nicht deklariert. Erkannte Musterverweise: ["app('ApplicationX').[' *']"]

Arbeiten mit Anwendungen auf mittlerer Ebene

Eine Anwendung auf mittlerer Ebene bietet ihren Benutzern die Möglichkeit, KQL zu verwenden und die Erfahrung zu verbessern, indem sie die Abfrageergebnisse mit erweiterten Daten aus dem internen Dienst bereichern.

Zu diesem Zweck stellt die Anwendung Benutzern eine Muster-Anweisung bereit, die tabellarische Daten zurückgibt, die ihre Benutzer in ihren Abfragen verwenden können. Die Argumente des Musters sind die Schlüssel, die die Anwendung zum Abrufen der Anreicherungsdaten verwendet.

Wenn der Benutzer die Abfrage ausführt, analysiert die Anwendung die Abfrage nicht selbst, sondern verwendet stattdessen den von einem leeren Muster zurückgegebenen Fehler, um die benötigten Schlüssel abzurufen. Daher stellt sie die Abfrage der leeren Musterdeklaration voran, sendet sie zur Verarbeitung an den Cluster und analysiert dann den zurückgegebenen HTTP-Header, um die Werte fehlender Musterargumente abzurufen. Die Anwendung verwendet diese Werte, um die Anreicherungsdaten nachzuschlagen, und erstellt eine neue Deklaration, die die entsprechende Anreicherungsdatenzuordnung definiert.

Schließlich stellt die Anwendung der Abfrage die neue Definition voran, sendet sie erneut zur Verarbeitung und gibt das Ergebnis zurück, das sie an den Benutzer erhält.

Beispiel

In den Beispielen wird ein Muster deklariert, definiert und anschließend aufgerufen.

Deklarieren eines leeren Musters

In diesem Beispiel erweitert eine Anwendung auf mittlerer Ebene Abfragen mit Längen-/Breitengradpositionen. Die Anwendung verwendet einen internen Dienst zum Zuordnen von IP-Adressen zu Längen-/Breitengradstandorten und stellt ein Muster namens map_ip_to_longlatbereit. Wenn die Abfrage ausgeführt wird, wird ein Fehler mit fehlenden Musterdefinitionen zurückgegeben:

map_ip_to_longlat("10.10.10.10")

Deklarieren und Definieren eines Musters

Die Anwendung analysiert diese Abfrage nicht und weiß daher nicht, welche IP-Adresse (10.10.10.10) an das Muster übergeben wurde. Daher wird der Benutzerabfrage eine leere map_ip_to_longlat Musterdeklaration vorangestellt und zur Verarbeitung gesendet:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Die Anwendung empfängt den folgenden Fehler als Antwort.

Mindestens ein Musterverweise wurden nicht deklariert. Erkannte Musterverweise: ["map_ip_to_longlat('10.10.10.10')"]

Aufrufen eines Musters

Die Anwendung prüft den Fehler, ermittelt, dass der Fehler einen fehlenden Musterverweis angibt und die fehlende IP-Adresse abruft (10.10.10.10). Es verwendet die IP-Adresse, um die Anreicherungsdaten in seinem internen Dienst nachzuschlagen und ein neues Muster zu erstellen, das die Zuordnung der IP-Adresse zu den entsprechenden Längengrad- und Breitengraddaten definiert. Das neue Muster wird der Abfrage des Benutzers vorangestellt und erneut ausgeführt.

Dieses Mal ist die Abfrage erfolgreich, da die Anreicherungsdaten jetzt in der Abfrage deklariert sind und das Ergebnis an den Benutzer gesendet wird.

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

Ausgabe-

Lat Long
37.405992 -122.078515