Sdílet prostřednictvím

Příkaz Pattern

  • Článek

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

Vzor je konstrukce, která mapuje řetězcové řazené kolekce členů na tabulkové výrazy.

Každý vzor musí deklarovat název vzoru a volitelně definovat mapování vzorů. Vzory, které definují mapování, při vyvolání vrací tabulkový výraz. Oddělte všechny dva příkazy 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í jazyka KQL (Kusto Query Language), 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.

Syntax

  • Deklarujte prázdný vzor:

    declare pattern PatternName;

  • Deklarujte a definujte vzor:

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

    {

           ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={výraz1};

        [ (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

Jméno Typ Požadovaný 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
PathName 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 PathName řazené kolekce členů, které se mají mapovat na výraz .
PathValue string Hodnota mapovaná pro PathName.
výrazu 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 clusteru nápovědy existuje databáze Samples s tabulkou StormEvents.

V těchto příkladech je definován vzor.

Definování jednoduchého vzoru

Tento příklad definuje vzor, který mapuje stavy na výraz, který vrací hlavní město nebo hlavní město.

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ýstupní

Kapitál
Edmonton

Definování vzoru s vymezeným oborem

Tento příklad definuje vzor pro určení rozsahu dat a metrik aplikačních dat. Vzor se vyvolá, aby se vrátila sjednocení dat.

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ýstupní

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

sémantickou chybu výstupu

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 sama dotaz parsuje, ale místo toho k načtení klíčů, které vyžaduje, použije chybu vrácenou prázdným vzorem. 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ředpne novou definici dotazu, znovu ji odešle ke zpracování a vrátí výsledek, který obdrží uživateli.

Příklad

V příkladech se deklaruje, definuje a potom vyvolá vzor.

Deklarace prázdného vzoru

V tomto příkladu aplikace střední vrstvy rozšiřuje 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 označovaný jako map_ip_to_longlat. Při spuštění dotazu vrátí chybu s chybějícími definicemi vzorů:

map_ip_to_longlat("10.10.10.10")

Deklarace a definování vzoru

Aplikace tento dotaz neanalyzuje, a proto neví, která IP adresa (10.10.10.10) byla předána vzoru. Předzálohuje tak uživatelský dotaz prázdnou deklarací vzoru map_ip_to_longlat 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')"]

Vyvolání vzoru

Aplikace zkontroluje chybu, zjistí, že chyba označuje chybějící odkaz na vzor a načte chybějící IP adresu (10.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.

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ýstupní

Lat Long
37.405992 -122.078515