Mönsteruttryck

Gäller för: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Ett mönster är en konstruktion som mappar strängtupplar till tabelluttryck.

Varje mönster måste deklarera ett mönsternamn och eventuellt definiera en mönstermappning. Mönster som definierar en mappning returnerar ett tabelluttryck när det anropas. Avgränsa två uttryck med ett semikolon.

Tomma mönster är mönster som deklareras men inte definierar en mappning. När de anropas returnerar de fel SEM0036 tillsammans med information om de saknade mönsterdefinitionerna i HTTP-huvudet.

Mellannivåprogram som tillhandahåller en KQL-upplevelse (Kusto Query Language) kan använda den returnerade informationen som en del av processen för att berika KQL-frågeresultat. Mer information finns i Arbeta med mellannivåprogram.

Syntax

• Deklarera ett tomt mönster:

  declare pattern PatternName;

• Deklarera och definiera ett mönster:

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

  {

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

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

  } ;

• Anropa ett mönster:

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

Läs mer om syntaxkonventioner.

Parametrar

Namn	Typ	Krävs	Beskrivning
PatternName	string	✔️	Namnet på mönstret.
ArgName	string	✔️	Namnet på argumentet. Mönster kan ha ett eller flera argument.
ArgType	string	✔️	Den skalära datatypen för argumentet ArgName. Möjliga värden: string
PathName	string		Namnet på sökvägsargumentet. Mönster får inte ha någon sökväg eller en enda sökväg.
PathArgType	string		Typen av argumentet PathArgType. Möjliga värden: string
ArgValue	string	✔️	ArgName och valfria PathName tuppelns värden som ska mappas till ett uttryck.
PathValue	string		Värdet som ska mappas för PathName.
uttryck	string	✔️	Ett tabell- eller lambda-uttryck som refererar till en funktion som returnerar tabelldata. Till exempel: Logs | where Timestamp > ago(1h)

Exempel

I hjälpklusterfinns det en Samples databas med en StormEvents tabell.

I de här exemplen definieras ett mönster.

Definiera ett enkelt mönster

Det här exemplet definierar ett mönster som mappar tillstånd till ett uttryck som returnerar dess huvudstad/större stad.

Kör frågan

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

utdata

Kapital
Edmonton

Definiera ett omfångsmönster

Det här exemplet definierar ett mönster för att begränsa data och mått för programdata. Mönstret anropas för att returnera en union av data.

Kör frågan

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

utdata

App	Data	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

Normalisering

Det finns syntaxvariationer för att anropa mönster. Följande union returnerar till exempel ett enda mönsteruttryck eftersom alla anrop har samma mönster.

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

Inga jokertecken

Det finns ingen särskild behandling som ges till jokertecken i ett mönster. Följande fråga returnerar till exempel ett enda mönsteranrop som saknas.

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

utdatasemantiska fel

En eller flera mönsterreferenser deklarerades inte. Identifierade mönsterreferenser: ["app('ApplicationX').[' *']"]

Arbeta med mellannivåprogram

Ett mellannivåprogram ger användarna möjlighet att använda KQL och vill förbättra upplevelsen genom att utöka frågeresultaten med förhöjda data från den interna tjänsten.

I detta syfte ger programmet användarna en mönsterinstruktur som returnerar tabelldata som användarna kan använda i sina frågor. Mönstrets argument är de nycklar som programmet använder för att hämta berikningsdata.

När användaren kör frågan parsar programmet inte själva frågan, utan använder i stället felet som returneras av ett tomt mönster för att hämta de nycklar som krävs. Så den förbereder frågan med den tomma mönsterdeklarationen, skickar den till klustret för bearbetning och parsar sedan det returnerade HTTP-huvudet för att hämta värdena för saknade mönsterargument. Programmet använder dessa värden för att leta upp berikningsdata och skapar en ny deklaration som definierar lämplig datamappning för berikande.

Slutligen förbereder programmet den nya definitionen för frågan, skickar den igen för bearbetning och returnerar det resultat som den får till användaren.

Exempel

I exemplen deklareras ett mönster, definieras och anropas sedan.

Deklarera ett tomt mönster

I det här exemplet berikar ett mellannivåprogram frågor med longitud-/latitudplatser. Programmet använder en intern tjänst för att mappa IP-adresser till longitud-/latitudplatser och ger ett mönster som kallas map_ip_to_longlat. När frågan körs returneras ett fel med saknade mönsterdefinitioner:

map_ip_to_longlat("10.10.10.10")

Deklarera och definiera ett mönster

Programmet parsar inte den här frågan och vet därför inte vilken IP-adress (10.10.10.10) som skickades till mönstret. Därför förbereds användarfrågan med en tom map_ip_to_longlat mönsterdeklaration och skickar den för bearbetning:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Programmet får följande fel som svar.

En eller flera mönsterreferenser deklarerades inte. Identifierade mönsterreferenser: ["map_ip_to_longlat('10.10.10.10')"]

Anropa ett mönster

Programmet inspekterar felet, fastställer att felet anger en mönsterreferens som saknas och hämtar den saknade IP-adressen (10.10.10.10). Den använder IP-adressen för att leta upp berikningsdata i sin interna tjänst och skapar ett nytt mönster som definierar mappningen av IP-adressen till motsvarande longitud- och latituddata. Det nya mönstret förbereds för användarens fråga och körs igen.

Den här gången lyckas frågan eftersom berikningsdata nu deklareras i frågan och resultatet skickas till användaren.

Kör frågan

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

utdata

Lat	Long
37.405992	-122.078515