Instrução de padrão

Um padrão é uma construção que mapeia cadeias de carateres para expressões tabulares. Cada padrão tem de declarar um nome de padrão e, opcionalmente, definir um mapeamento de padrões. Os padrões que definem um mapeamento devolvem uma expressão tabular quando invocado. As duas instruções têm de ser separadas por ponto e vírgula.

Os padrões vazios são padrões que são declarados, mas não definem um mapeamento. Quando invocados, devolvem o erro SEM0036 juntamente com os detalhes das definições de padrão em falta no cabeçalho HTTP. As aplicações de camada média que fornecem uma experiência de Linguagem de Pesquisa Kusto (KQL) podem utilizar os detalhes devolvidos como parte do processo para enriquecer os resultados da consulta KQL. Para obter mais informações, veja Trabalhar com aplicações de camada média.

Syntax

• Declarar um padrão vazio:

  declarepatternPatternName;

• Declarar e definir um padrão:

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

  {

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

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

  } ;

• Invocar um padrão:

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Tipo	Necessário	Descrição
PatternName	string	✔️	O nome do padrão.
ArgName	string	✔️	O nome do argumento. Os padrões podem ter um ou mais argumentos.
ArgType	string	✔️	O tipo de dados escalar do argumento ArgName . Valores possíveis: string
PathName	string		O nome do argumento caminho. Os padrões não podem ter um caminho ou um caminho.
PathArgType	string		O tipo do argumento PathArgType . Valores possíveis: string
ArgValue	string	✔️	Os valores de cadeia de identificação ArgName e PathName opcionais a serem mapeados para uma expressão.
PathValue	string		O valor a mapear para PathName.
expression	string	✔️	Uma expressão tabular ou lambda que referencia uma função que devolve dados tabulares. Por exemplo: Logs | where Timestamp > ago(1h)

Exemplos

Em cada um dos seguintes exemplos, um padrão é declarado, definido e, em seguida, invocado.

Definir padrões simples

O exemplo seguinte define um padrão que mapeia estados para uma expressão que devolve a capital/cidade principal.

Executar a consulta

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

Saída

Capital
Edmonton

Executar a consulta

O exemplo seguinte define um padrão que define alguns dados de aplicação no âmbito.

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

Saída

Aplicação	Dados	Métricas
Aplicação n.º 2	9
Aplicação n.º 2	8
Aplicação n.º 2	7
Aplicação n.º 2	6
Aplicação n.º 2	5
Aplicação n.º 1		0.53674122855537532
Aplicação n.º 1		0.78304713305654439
Aplicação n.º 1		0.20168860732346555
Aplicação n.º 1		0.13249123867679469
Aplicação n.º 1		0.19388305330563443

Normalização

Existem variações de sintaxe para invocar padrões. Por exemplo, a união seguinte devolve uma expressão de padrão único, uma vez que todas as invocações têm o mesmo padrão.

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

Sem carateres universais

Não há tratamento especial dado aos carateres universais num padrão. Por exemplo, a consulta seguinte devolve uma única invocação de padrão em falta.

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

Devolve um erro semântico

Uma ou mais referências de padrão não foram declaradas. Referências de padrões detetadas: ["app('ApplicationX').[' *']"]

Trabalhar com aplicações de camada média

Uma aplicação de camada média fornece aos seus utilizadores a capacidade de utilizar kQL e quer melhorar a experiência ao enriquecer os resultados da consulta com dados aumentados do seu serviço interno.

Para tal, a aplicação fornece aos utilizadores uma instrução de padrão que devolve dados tabulares que os utilizadores podem utilizar nas respetivas consultas. Os argumentos do padrão são as chaves que a aplicação utilizará para obter os dados de melhoramento. Quando o utilizador executa a consulta, a aplicação não analisa a própria consulta, mas planeia tirar partido do erro devolvido por um padrão vazio para obter as chaves necessárias. Assim, prepara a consulta com a declaração de padrão vazia, envia-a para o cluster para processamento e, em seguida, analisa o cabeçalho HTTP devolvido para obter os valores dos argumentos de padrão em falta. A aplicação utiliza estes valores para procurar os dados de melhoramento e cria uma nova declaração que define o mapeamento de dados de melhoramento adequado. Por fim, a aplicação prepara a nova definição para a consulta do utilizador, reenvia-a para processamento e devolve o resultado que recebe ao utilizador.

Exemplo

No exemplo seguinte, uma aplicação de camada média fornece a capacidade de enriquecer as consultas com localizações de longitude/latitude. A aplicação utiliza um serviço interno para mapear endereços IP para localizações de longitude/latitude e fornece um padrão chamado map_ip_to_longlat para esta finalidade. Vamos supor que a aplicação obtém a seguinte consulta do utilizador:

map_ip_to_longlat("10.10.10.10")

A aplicação não analisa esta consulta e, por conseguinte, não sabe que endereço IP (10.10.10.10) foi transmitido para o padrão. Assim, prepara a consulta do utilizador com uma declaração de padrão vazia map_ip_to_longlat e envia-a para processamento:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

A aplicação recebe o seguinte erro na resposta.

Uma ou mais referências de padrão não foram declaradas. Referências de padrões detetadas: ["map_ip_to_longlat('10.10.10.10')"]

A aplicação inspeciona o erro, determina que o erro indica uma referência de padrão em falta e obtém o endereço IP em falta (10.10.10.10). Utiliza o endereço IP para procurar os dados de melhoramento no seu serviço interno e cria um novo padrão que define o mapeamento do endereço IP para os dados de longitude e latitude correspondentes. O novo padrão é anexado à consulta do utilizador e executado novamente. Desta vez, a consulta é bem-sucedida porque os dados de melhoramento são agora declarados na consulta e o resultado é enviado ao utilizador.

Executar a consulta

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

Saída

Lat	Long
37.405992	-122.078515

Esta capacidade não é suportada no Azure Monitor.