Patrooninstructie

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel-

Een patroon is een constructie waarmee tekenreeks tuples worden toegewezen aan tabellaire expressies.

Elk patroon moet declareren een patroonnaam en eventueel definiëren een patroontoewijzing. Patronen die een toewijzing definiëren, retourneren een tabellaire expressie wanneer deze wordt aangeroepen. Scheid twee instructies 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 Query Language) bieden, kunnen de geretourneerde details gebruiken als onderdeel van hun proces om KQL-queryresultaten te verrijken. Zie Werken met toepassingen in de middelste laagvoor meer informatie.

Syntaxis

• Een leeg patroon declareren:

  declare pattern PatternName-;

• Een patroon declareren en definiëren:

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

  {

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

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

  } ;

• Een patroon aanroepen:

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

Meer informatie over syntaxisconventies.

Parameters

Voorbeelden

In de voorbeelden in deze sectie ziet u hoe u de syntaxis kunt gebruiken om aan de slag te gaan.

Een eenvoudig patroon definiëren

In dit voorbeeld wordt een patroon gedefinieerd waarmee staten worden toegewezen aan een expressie die de hoofd-/hoofdstad retourneert.

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

Een bereikpatroon definiëren

In dit voorbeeld wordt een patroon gedefinieerd voor het bereik van gegevens en metrische gegevens van toepassingsgegevens. Het patroon wordt aangeroepen om een samenvoeging van de gegevens te retourneren.

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

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 is geen speciale behandeling gegeven aan jokertekens in een patroon. Met de volgende query wordt bijvoorbeeld één ontbrekend patroon aanroepen geretourneerd.

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

semantische uitvoerfout

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 de gebruikers de mogelijkheid om KQL te gebruiken en wil de ervaring verbeteren door de queryresultaten te verrijken met uitgebreide gegevens van de interne service.

Daartoe biedt de toepassing gebruikers een patrooninstructie die tabelgegevens retourneert die hun gebruikers kunnen gebruiken in hun query's. 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 zelf niet, maar gebruikt in plaats daarvan de fout 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 waarmee de juiste verrijkingsgegevenstoewijzing wordt gedefinieerd.

Ten slotte wordt de nieuwe definitie voorafgegaan door de toepassing aan de query, wordt deze opnieuw verzonden voor verwerking en wordt het resultaat geretourneerd dat deze aan de gebruiker ontvangt.

Voorbeeld

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

Een leeg patroon declareren

In dit voorbeeld verrijkt een toepassing in de middelste laag query's met locaties voor lengte- en breedtegraad. De toepassing maakt gebruik van een interne service om IP-adressen toe te wijzen aan locaties voor lengtegraad/breedtegraad en biedt een patroon met de naam map_ip_to_longlat. Wanneer de query wordt uitgevoerd, wordt er een fout geretourneerd met ontbrekende patroondefinities:

map_ip_to_longlat("10.10.10.10")

Een patroon declareren en definiëren

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

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

De toepassing ontvangt de volgende fout in reactie.

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

Een patroon aanroepen

De toepassing inspecteert de fout, bepaalt dat de fout een verwijzing naar een ontbrekend patroon aangeeft en het ontbrekende IP-adres (10.10.10.10). Het maakt gebruik van het IP-adres om de verrijkingsgegevens in de interne service op te zoeken en maakt een nieuw patroon dat de toewijzing van het IP-adres aan de bijbehorende lengte- en breedtegraadgegevens definieert. Het nieuwe patroon wordt voorafgegaan door de query van de gebruiker en wordt opnieuw uitgevoerd.

Deze keer slaagt de query omdat de verrijkingsgegevens nu in de query worden gedeclareerd en het resultaat naar de gebruiker wordt verzonden.

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