Instrução PATTERN

Um padrão é um constructo que mapeia tuplas de cadeia de caracteres para expressões tabulares. Cada padrão deve declarar um nome de padrão e, opcionalmente, definir um mapeamento de padrão. Os padrões que definem um mapeamento retornam uma expressão tabular quando invocado. Duas instruções devem ser sempre separadas por ponto e vírgula.

Padrões vazios são padrões declarados, mas não definem um mapeamento. Quando invocados, eles retornam o erro SEM0036 juntamente com os detalhes das definições de padrão ausentes no cabeçalho HTTP. Aplicativos de camada intermediária que fornecem uma experiência de Linguagem de Consulta Kusto (KQL) podem usar os detalhes retornados como parte de seu processo para enriquecer os resultados da consulta KQL. Para obter mais informações, consulte Trabalhando com aplicativos de camada intermediária.

Syntax

• Declare um padrão vazio:

  declarepatternPatternName;

• Declare e defina 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	Obrigató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 path. Os padrões não podem ter nenhum caminho ou um caminho.
PathArgType	string		O tipo do argumento PathArgType . Valores possíveis: string
ArgValue	string	✔️	Os valores de tupla ArgName e PathName opcionais a serem mapeados para uma expressão.
PathValue	string		O valor a ser mapeado para PathName.
expressão	string	✔️	Uma expressão tabular ou lambda que faz referência a uma função que retorna dados tabulares. Por exemplo: Logs | where Timestamp > ago(1h)

Exemplos

Em cada um dos exemplos a seguir, um padrão é declarado, definido e invocado.

Definir padrões simples

O exemplo a seguir define um padrão que mapeia estados para uma expressão que retorna sua 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 a seguir define um padrão que define alguns dados de aplicativo com escopo.

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

Aplicativo	Dados	Métricas
Aplicativo nº 2	9
Aplicativo nº 2	8
Aplicativo nº 2	7
Aplicativo nº 2	6
Aplicativo nº 2	5
Aplicativo nº 1		0.53674122855537532
Aplicativo nº 1		0.78304713305654439
Aplicativo nº 1		0.20168860732346555
Aplicativo nº 1		0.13249123867679469
Aplicativo nº 1		0.19388305330563443

Normalização

Há variações de sintaxe para invocar padrões. Por exemplo, a união a seguir retorna uma única expressão de padrão, pois todas as invocações são do 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 curingas

Não há tratamento especial dado a curingas em um padrão. Por exemplo, a consulta a seguir retorna uma única invocação de padrão ausente.

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

Retorna erro semântico

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

Trabalhar com aplicativos de camada intermediária

Um aplicativo de camada intermediária fornece aos usuários a capacidade de usar o KQL e deseja aprimorar a experiência enriquecendo os resultados da consulta com dados aumentados de seu serviço interno.

Para isso, o aplicativo fornece aos usuários uma instrução padrão que retorna dados tabulares que seus usuários podem usar em suas consultas. Os argumentos do padrão são as chaves que o aplicativo usará para recuperar os dados de enriquecimento. Quando o usuário executa a consulta, o aplicativo não analisa a consulta em si, mas planeja aproveitar o erro retornado por um padrão vazio para recuperar as chaves necessárias. Portanto, ele 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 retornado para recuperar os valores de argumentos padrão ausentes. O aplicativo usa esses valores para pesquisar os dados de enriquecimento e cria uma nova declaração que define o mapeamento de dados de enriquecimento apropriado. Por fim, o aplicativo prepara a nova definição para a consulta do usuário, reenvia-a para processamento e retorna o resultado que recebe ao usuário.

Exemplo

No exemplo a seguir, um aplicativo de camada intermediária fornece a capacidade de enriquecer consultas com locais de longitude/latitude. O aplicativo usa um serviço interno para mapear endereços IP para locais de longitude/latitude e fornece um padrão chamado map_ip_to_longlat para essa finalidade. Vamos supor que o aplicativo obtenha a seguinte consulta do usuário:

map_ip_to_longlat("10.10.10.10")

O aplicativo não analisa essa consulta e, portanto, não sabe qual endereço IP (10.10.10.10) foi passado para o padrão. Portanto, ele prepara a consulta do usuário com uma declaração de padrão vazia map_ip_to_longlat e a envia para processamento:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

O aplicativo recebe o seguinte erro em resposta.

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

O aplicativo inspeciona o erro, determina que o erro indica uma referência de padrão ausente e recupera o endereço IP ausente (10.10.10.10). Ele usa o endereço IP para pesquisar os dados de enriquecimento em seu serviço interno e cria um novo padrão definindo o mapeamento do endereço IP para os dados de longitude e latitude correspondentes. O novo padrão é anexado à consulta do usuário e executado novamente. Desta vez, a consulta é bem-sucedida porque os dados de enriquecimento agora são declarados na consulta e o resultado é enviado ao usuário.

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

Não há suporte para essa funcionalidade no Azure Monitor.