Instrukcja Pattern

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Wzorzec to konstrukcja, która mapuje krotki ciągów na wyrażenia tabelaryczne.

Każdy wzorzec musi zadeklarować nazwę wzorca i opcjonalnie zdefiniować mapowanie wzorca. Wzorce definiujące mapowanie zwracają wyrażenie tabelaryczne podczas wywoływania. Rozdziel wszystkie dwie instrukcje średnikami.

Puste wzorce to wzorce zadeklarowane, ale nie definiują mapowania. Po wywołaniu zwracają błąd SEM0036 wraz ze szczegółami brakujących definicji wzorca w nagłówku HTTP.

Aplikacje warstwy środkowej, które zapewniają środowisko języka KQL (Kusto Query Language), mogą używać zwróconych szczegółów w ramach procesu w celu wzbogacania wyników zapytań języka KQL. Aby uzyskać więcej informacji, zobacz Praca z aplikacjami warstwy środkowej.

Składnia

• Zadeklaruj pusty wzorzec:

  declare pattern PatternName;

• Deklarowanie i definiowanie wzorca:

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

  {

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

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

  } ;

• Wywołaj wzorzec:

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

Dowiedz się więcej na temat konwencji składni .

Parametry

Przykłady

W przykładach w tej sekcji pokazano, jak używać składni, aby ułatwić rozpoczęcie pracy.

Definiowanie prostego wzorca

W tym przykładzie zdefiniowano wzorzec mapujący stany na wyrażenie zwracające jego stolicę/główne miasto.

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

wyjściowe

Definiowanie wzorca o określonym zakresie

W tym przykładzie zdefiniowano wzorzec określający zakres danych i metryk danych aplikacji. Wzorzec jest wywoływany w celu zwrócenia unii danych.

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

wyjściowe

Normalizacja

Istnieją odmiany składni dotyczące wywoływania wzorców. Na przykład następująca unia zwraca pojedyncze wyrażenie wzorca, ponieważ wszystkie wywołania są tego samego wzorca.

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

Brak symboli wieloznacznych

Nie ma specjalnego traktowania dla symboli wieloznacznych w wzorcu. Na przykład następujące zapytanie zwraca jedno brakujące wywołanie wzorca.

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

błąd semantyczny danych wyjściowych

Nie zadeklarowano co najmniej jednego odwołania do wzorca. Wykryte odwołania do wzorca: ["app('ApplicationX').[" *']"]

Praca z aplikacjami warstwy środkowej

Aplikacja warstwy środkowej zapewnia swoim użytkownikom możliwość korzystania z języka KQL i chce ulepszyć środowisko, wzbogacając wyniki zapytania o rozszerzone dane z wewnętrznej usługi.

W tym celu aplikacja udostępnia użytkownikom instrukcję wzorca zwracającą dane tabelaryczne, których użytkownicy mogą używać w zapytaniach. Argumenty wzorca to klucze, których aplikacja będzie używać do pobierania danych wzbogacania.

Gdy użytkownik uruchamia zapytanie, aplikacja nie analizuje samego zapytania, ale używa błędu zwróconego przez pusty wzorzec, aby pobrać wymagane klucze. Dlatego poprzedza zapytanie z pustą deklaracją wzorca, wysyła je do klastra do przetwarzania, a następnie analizuje zwrócony nagłówek HTTP, aby pobrać wartości brakujących argumentów wzorca. Aplikacja używa tych wartości do wyszukiwania danych wzbogacania i tworzy nową deklarację, która definiuje odpowiednie mapowanie danych wzbogacania.

Na koniec aplikacja poprzedza nową definicję zapytania, ponownie wysyła ją do przetwarzania i zwraca wynik otrzymany do użytkownika.

Przykład

W przykładach wzorzec jest zadeklarowany, zdefiniowany, a następnie wywoływany.

Deklarowanie pustego wzorca

W tym przykładzie aplikacja warstwy środkowej wzbogaca zapytania o lokalizacje długości/szerokości geograficznej. Aplikacja używa usługi wewnętrznej do mapowania adresów IP na lokalizacje długości/szerokości geograficznej i udostępnia wzorzec o nazwie map_ip_to_longlat. Po uruchomieniu zapytania zwraca błąd z brakującymi definicjami wzorca:

map_ip_to_longlat("10.10.10.10")

Deklarowanie i definiowanie wzorca

Aplikacja nie analizuje tego zapytania i dlatego nie wie, który adres IP (10.10.10.10.10) został przekazany do wzorca. Dlatego poprzedza zapytanie użytkownika pustą deklaracją wzorca map_ip_to_longlat i wysyła je do przetwarzania:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

Aplikacja otrzymuje następujący błąd w odpowiedzi.

Nie zadeklarowano co najmniej jednego odwołania do wzorca. Wykryte odwołania do wzorca: ["map_ip_to_longlat('10.10.10.10')"]

Wywoływanie wzorca

Aplikacja sprawdza błąd, określa, że błąd wskazuje brak odwołania do wzorca i pobiera brakujący adres IP (10.10.10.10.10). Używa ona adresu IP do wyszukiwania danych wzbogacania w usłudze wewnętrznej i tworzy nowy wzorzec definiujący mapowanie adresu IP na odpowiednie dane długości geograficznej i szerokości geograficznej. Nowy wzorzec jest poprzedzany zapytaniem użytkownika i uruchamiany ponownie.

Tym razem zapytanie powiedzie się, ponieważ dane wzbogacania są teraz zadeklarowane w zapytaniu, a wynik jest wysyłany do użytkownika.

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

wyjściowe