Instrukcja wzorca

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. Wszystkie dwie instrukcje muszą być oddzielone średnikiem.

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ęzyk zapytań Kusto (KQL), mogą używać zwróconych szczegółów w ramach procesu w celu wzbogacania wyników zapytań KQL. Aby uzyskać więcej informacji, zobacz Praca z aplikacjami warstwy środkowej.

Składnia

• Zadeklaruj pusty wzorzec:

  declarepattern PatternName ;

• Deklarowanie i definiowanie wzorca:

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

  {

        ( ArgValue1_1 [ , ArgValue2_1, ... ] ) [ .[ PathValue_1 ] ] { = wyrażenie1 } ;

      [ 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

Nazwisko	Type	Wymagania	opis
PatternName	string	✔️	Nazwa wzorca.
ArgName	string	✔️	Nazwa argumentu. Wzorce mogą mieć co najmniej jeden argument.
ArgType	string	✔️	Typ danych skalarnych argumentu ArgName . Możliwe wartości: string
Nazwa_ścieżki	string		Nazwa argumentu ścieżki. Wzorce nie mogą mieć ścieżki ani jednej ścieżki.
PathArgType	string		Typ argumentu PathArgType . Możliwe wartości: string
ArgValue	string	✔️	Wartości krotki ArgName i opcjonalne pathName , które mają być mapowane na wyrażenie.
PathValue	string		Wartość do mapowania dla pathName.
wyrażenie	string	✔️	Wyrażenie tabelaryczne lub lambda odwołujące się do funkcji zwracającej dane tabelaryczne. Na przykład: Logs | where Timestamp > ago(1h).

Przykłady

W każdym z poniższych przykładów wzorzec jest deklarowany, definiowany, a następnie wywoływany.

Definiowanie prostych wzorców

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

Uruchamianie zapytania

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ście

Kapitał
Edmonton

Uruchamianie zapytania

W poniższym przykładzie zdefiniowano wzorzec definiujący niektóre dane aplikacji o określonym zakresie.

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ście

Aplikacja	Data	Metryki
Aplikacja 2	9
Aplikacja 2	8
Aplikacja 2	7
Aplikacja 2	6
Aplikacja 2	5
Aplikacja 1		0.53674122855537532
Aplikacja 1		0.78304713305654439
Aplikacja 1		0.20168860732346555
Aplikacja 1		0.13249123867679469
Aplikacja 1		0.19388305330563443

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

Zwraca błąd semantyczny

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 planuje skorzystać z błędu zwróconego przez pusty wzorzec w celu pobrania kluczy, których wymaga. 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 użytkownika, ponownie wysyła ją do przetwarzania i zwraca wynik otrzymany użytkownikowi.

Przykład

W poniższym przykładzie aplikacja warstwy środkowej umożliwia wzbogacanie zapytań 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 geograficznej/szerokości geograficznej i udostępnia wzorzec wywoływany map_ip_to_longlat w tym celu. Załóżmy, że aplikacja pobiera następujące zapytanie od użytkownika:

map_ip_to_longlat("10.10.10.10")

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ą map_ip_to_longlat deklaracją wzorca 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')"]

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.

Uruchamianie zapytania

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ście

Lat	Long
37.405992	-122.078515

Ta funkcja nie jest obsługiwana w usłudze Azure Monitor.