Příkaz pattern

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Vzor je konstrukce, která mapuje řazené kolekce členů řetězců na tabulkové výrazy. Každý vzor musí deklarovat název vzoru a volitelně definovat mapování vzoru. Vzory, které definují mapování, při vyvolání vrací tabulkový výraz. Všechny dva příkazy musí být oddělené středníkem.

Prázdné vzory jsou vzory , které jsou deklarovány, ale nedefinují mapování. Při vyvolání vrátí chybu SEM0036 spolu s podrobnostmi chybějících definic vzorů v hlavičce HTTP. Aplikace střední vrstvy, které poskytují prostředí dotazovací jazyk Kusto (KQL), můžou v rámci procesu využívat vrácené podrobnosti k obohacení výsledků dotazů KQL. Další informace najdete v tématu Práce s aplikacemi střední vrstvy.

Syntaxe

• Deklarujte prázdný vzor:

  declarepattern PatternName ;

• Deklarujte a definujte vzor:

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

  {

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

      [ ( ArgValue1_2 [, ArgValue2_2, ... ] ) [ .[ PathValue_2 ] ] { = výraz2 } ; ... ]

  } ;

• Vyvolání vzoru:

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

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Type	Požadováno	Popis
PatternName	string	✔️	Název vzoru.
ArgName	string	✔️	Název argumentu. Vzory můžou mít jeden nebo více argumentů.
ArgType	string	✔️	Skalární datový typ argumentu ArgName . Možné hodnoty: string
Cesta k souboru	string		Název argumentu cesty. Vzory nemohou mít žádnou cestu nebo jednu cestu.
PathArgType	string		Typ argumentu PathArgType . Možné hodnoty: string
ArgValue	string	✔️	ArgName a volitelné hodnoty řazené kolekce členů PathName, které se mají namapovat na výraz.
PathValue	string		Hodnota, která se má mapovat pro PathName.
výraz	string	✔️	Tabulkový výraz nebo výraz lambda, který odkazuje na funkci vracející tabulková data. Příklad: Logs | where Timestamp > ago(1h)

Příklady

V každém z následujících příkladů je model deklarován, definován a následně vyvolán.

Definování jednoduchých vzorů

Následující příklad definuje vzor, který mapuje stavy na výraz, který vrací jeho hlavní město nebo hlavní město.

Spuštění dotazu

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

Výstup

Hlavní město
Edmonton

Spuštění dotazu

Následující příklad definuje vzor, který definuje některá vymezená data aplikace.

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

Výstup

Aplikace	Data	Metriky
Aplikace č. 2	9
Aplikace č. 2	8
Aplikace č. 2	7
Aplikace č. 2	6
Aplikace č. 2	5
Aplikace č. 1		0.53674122855537532
Aplikace č. 1		0.78304713305654439
Aplikace č. 1		0.20168860732346555
Aplikace č. 1		0.13249123867679469
Aplikace č. 1		0.19388305330563443

Normalizace

Existují varianty syntaxe pro vyvolání vzorů. Například následující sjednocení vrátí jeden vzorový výraz, protože všechny vyvolání mají stejný vzor.

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

Žádné zástupné kóty

Ve vzorci neexistuje zvláštní zacházení se zástupnými cardy. Například následující dotaz vrátí jedno vyvolání vzoru.

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

Vrátí sémantickou chybu.

Jeden nebo více odkazů na vzor nebyl deklarován. Zjištěné odkazy na vzory: ["app('ApplicationX').[' *']"]

Práce s aplikacemi střední vrstvy

Aplikace střední vrstvy poskytuje uživatelům možnost používat KQL a chce vylepšit prostředí obohacením výsledků dotazu o rozšířená data z interní služby.

K tomuto účelu aplikace poskytuje uživatelům příkaz vzor, který vrací tabulková data, která mohou uživatelé použít v dotazech. Argumenty vzoru jsou klíče, které aplikace použije k načtení dat rozšiřování. Když uživatel spustí dotaz, aplikace neanalyduje samotný dotaz, ale plánuje využít chybu vrácenou prázdným vzorem k načtení klíčů, které vyžaduje. Proto předzálohuje dotaz s prázdnou deklarací vzoru, odešle ho do clusteru ke zpracování a pak parsuje vrácenou hlavičku HTTP, aby načetla hodnoty chybějících argumentů vzoru. Aplikace pomocí těchto hodnot vyhledá data rozšiřování a vytvoří novou deklaraci, která definuje vhodné mapování dat rozšiřování. Aplikace nakonec předpovědí novou definici dotazu uživatele, znovu ji odešle ke zpracování a vrátí výsledek, který uživateli přijme.

Příklad

V následujícím příkladu poskytuje aplikace střední vrstvy možnost rozšířit dotazy o umístění zeměpisné délky a zeměpisné šířky. Aplikace používá interní službu k mapování IP adres na umístění zeměpisné délky a zeměpisné šířky a poskytuje vzor, který se pro tento účel volá map_ip_to_longlat . Předpokládejme, že aplikace získá od uživatele následující dotaz:

map_ip_to_longlat("10.10.10.10")

Aplikace tento dotaz neanalyzuje, a proto neví, která IP adresa (10.10.10.10)) byla předána vzoru. Předzálohuje uživatelský dotaz prázdnou map_ip_to_longlat deklarací vzoru a odešle ho ke zpracování:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Aplikace obdrží v odpovědi následující chybu.

Jeden nebo více odkazů na vzor nebyl deklarován. Zjištěné odkazy na vzory: ["map_ip_to_longlat('10.10.10')"]

Aplikace zkontroluje chybu, určí, že tato chyba označuje chybějící odkaz na vzor a načte chybějící IP adresu (10.10.10.10). Pomocí IP adresy vyhledá data rozšiřování ve své interní službě a vytvoří nový vzor definující mapování IP adresy na odpovídající data zeměpisné délky a zeměpisné šířky. Nový vzor se předečte dotazu uživatele a spustí se znovu. Tentokrát bude dotaz úspěšný, protože data rozšiřování jsou nyní deklarována v dotazu a výsledek se odešle uživateli.

Spuštění dotazu

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

Výstup

Lat	Long
37.405992	-122.078515