Pattern-instructie

Een patroon is een constructie waarmee tuples van tekenreeksen worden toegewezen aan tabellaire expressies. Elk patroon moet een patroonnaam declareren en eventueel een patroontoewijzing definiëren . Patronen die een toewijzing definiëren, retourneren een tabellaire expressie wanneer deze wordt aangeroepen. Twee instructies moeten worden gescheiden door een puntkomma.

Lege patronen zijn patronen die worden gedeclareerd, maar geen toewijzing definiëren. Wanneer ze worden aangeroepen, retourneren ze een fout SEM0036 samen met de details van de ontbrekende patroondefinities in de HTTP-header. Toepassingen in de middelste laag die een KQL-ervaring (Kusto-querytaal) bieden, kunnen de geretourneerde gegevens gebruiken als onderdeel van hun proces om KQL-queryresultaten te verrijken. Zie Werken met toepassingen in de middelste laag voor meer informatie.

Syntax

• Declareer een leeg patroon:

  declarepatternPatternName;

• Declareer en definieer een patroon:

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

  {

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

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

  } ;

• Een patroon aanroepen:

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
PatternName	string	✔️	De naam van het patroon.
ArgName	string	✔️	De naam van het argument. Patronen kunnen een of meer argumenten hebben.
ArgType	string	✔️	Het scalaire gegevenstype van het argument ArgName . Mogelijke waarden: string
Padnaam	string		De naam van het padargument. Patronen kunnen geen pad of één pad hebben.
PathArgType	string		Het type van het argument PathArgType . Mogelijke waarden: string
ArgValue	string	✔️	De tuplewaarden ArgName en optioneel PathName die moeten worden toegewezen aan een expressie.
PathValue	string		De waarde die moet worden toegewezen voor PathName.
expression	string	✔️	Een tabellaire of lambda-expressie die verwijst naar een functie die gegevens in tabelvorm retourneert. Bijvoorbeeld: Logs | where Timestamp > ago(1h)

Voorbeelden

In elk van de volgende voorbeelden wordt een patroon gedeclareerd, gedefinieerd en vervolgens aangeroepen.

Eenvoudige patronen definiëren

In het volgende voorbeeld wordt een patroon gedefinieerd waarmee statussen worden toegewezen aan een expressie die de bijbehorende hoofdstad/grote stad retourneert.

De query uitvoeren

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

Uitvoer

Kapitaal
Edmonton

De query uitvoeren

In het volgende voorbeeld wordt een patroon gedefinieerd dat bepaalde toepassingsgegevens binnen het bereik definieert.

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

Uitvoer

App	Gegevens	Metrische gegevens
App 2	9
App 2	8
App 2	7
App 2	6
App 2	5
App 1		0.53674122855537532
App 1		0.78304713305654439
App 1		0.20168860732346555
App 1		0.13249123867679469
App 1		0.19388305330563443

Normalisatie

Er zijn syntaxisvariaties voor het aanroepen van patronen. De volgende samenvoeging retourneert bijvoorbeeld één patroonexpressie omdat alle aanroepen hetzelfde patroon hebben.

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

Geen jokertekens

Er wordt geen speciale behandeling gegeven aan jokertekens in een patroon. De volgende query retourneert bijvoorbeeld één ontbrekende patroon-aanroep.

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

Retourneert een semantische fout

Een of meer patroonverwijzingen zijn niet gedeclareerd. Gedetecteerde patroonverwijzingen: ["app('ApplicationX').[' *']"]

Werken met toepassingen in de middelste laag

Een toepassing in de middelste laag biedt gebruikers de mogelijkheid om KQL te gebruiken en wil de ervaring verbeteren door de queryresultaten te verrijken met uitgebreide gegevens uit de interne service.

Hiertoe biedt de toepassing gebruikers een patrooninstructie die tabelgegevens retourneert die hun gebruikers in hun query's kunnen gebruiken. De argumenten van het patroon zijn de sleutels die de toepassing gebruikt om de verrijkingsgegevens op te halen. Wanneer de gebruiker de query uitvoert, parseert de toepassing de query niet zelf, maar is het in plaats daarvan van plan de fout te gebruiken die wordt geretourneerd door een leeg patroon om de sleutels op te halen die nodig zijn. De query wordt dus voorafgegaan door de lege patroondeclaratie, verzendt deze naar het cluster voor verwerking en parseert vervolgens de geretourneerde HTTP-header om de waarden van ontbrekende patroonargumenten op te halen. De toepassing gebruikt deze waarden om de verrijkingsgegevens op te zoeken en een nieuwe declaratie te maken die de juiste toewijzing van verrijkingsgegevens definieert. Ten slotte past de toepassing de nieuwe definitie toe aan de query van de gebruiker, verzendt deze opnieuw voor verwerking en retourneert het resultaat dat deze ontvangt aan de gebruiker.

Voorbeeld

In het volgende voorbeeld biedt een toepassing in de middelste laag de mogelijkheid om query's te verrijken met lengtegraad/breedtegraadlocaties. De toepassing maakt gebruik van een interne service om IP-adressen toe te wijzen aan lengtegraad/breedtegraadlocaties en biedt een patroon dat voor dit doel wordt aangeroepen map_ip_to_longlat . Stel dat de toepassing de volgende query van de gebruiker ontvangt:

map_ip_to_longlat("10.10.10.10")

De toepassing parseert deze query niet en weet daarom niet welk IP-adres (10.10.10.10) aan het patroon is doorgegeven. De gebruikersquery wordt dus voorafgegaan door een lege map_ip_to_longlat patroondeclaratie en deze wordt verzonden voor verwerking:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

De toepassing ontvangt de volgende fout als reactie.

Een of meer patroonverwijzingen zijn niet gedeclareerd. Gedetecteerde patroonverwijzingen: ["map_ip_to_longlat('10.10.10.10')"]

De toepassing inspecteert de fout, bepaalt dat de fout een ontbrekende patroonreferentie aangeeft en haalt het ontbrekende IP-adres (10.10.10.10) op. Het ip-adres wordt gebruikt om de verrijkingsgegevens in de interne service op te zoeken en er wordt een nieuw patroon gemaakt waarin de toewijzing van het IP-adres aan de bijbehorende lengte- en breedtegraadgegevens wordt gedefinieerd. Het nieuwe patroon wordt voorafgegaan aan de query van de gebruiker en wordt opnieuw uitgevoerd. Deze keer slaagt de query omdat de verrijkingsgegevens nu worden gedeclareerd in de query en het resultaat naar de gebruiker wordt verzonden.

De query uitvoeren

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

Uitvoer

Lat	Long
37.405992	-122.078515

Deze mogelijkheid wordt niet ondersteund in Azure Monitor.