Declaração de padrão

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Um padrão é uma construção 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 invocados. Separe duas instruções por ponto-e-vírgula.

Padrões vazios são padrões que são declarados, mas não definem um mapeamento. Quando invocados, eles retornam SEM0036 de erro juntamente com os detalhes das definições de padrão ausentes no cabeçalho HTTP.

Os aplicativos de camada intermediária que fornecem uma experiência KQL (Kusto Query Language) 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.

Sintaxe

• Declare um padrão vazio:

  declare pattern ; PatternName

• Declare e defina um padrão:

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

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expressão1};

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

  } ;

• Invoque um padrão:

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Exemplos

No cluster de ajuda, há um banco de dados Samples com uma tabela StormEvents.

Nesses exemplos, um padrão é definido.

Definir um padrão simples

Este exemplo define um padrão que mapeia estados para uma expressão que retorna sua capital/cidade principal.

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

Output

Definir um padrão com escopo

Este exemplo define um padrão para dados de escopo e métricas de dados de aplicativos. O padrão é invocado para retornar uma união dos dados.

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

Output

Normalização

Existem variações de sintaxe para invocar padrões. Por exemplo, a união a seguir retorna uma única expressão de padrão, uma vez que 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 aos curingas em um padrão. Por exemplo, a consulta a seguir retorna uma única chamada 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

Erro semântico de saída

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

Trabalhar com aplicativos de camada intermediária

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

Para esse fim, o aplicativo fornece aos usuários uma instrução de 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 usa o erro retornado por um padrão vazio para recuperar as chaves necessárias. Assim, ele precede 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 dos argumentos de 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.

Finalmente, o aplicativo precede a nova definição para a consulta, reenvia-a para processamento e retorna o resultado que recebe ao usuário.

Exemplo

Nos exemplos, um padrão é declarado, definido e, em seguida, invocado.

Declarar um padrão vazio

Neste exemplo, um aplicativo de camada intermediária enriquece as 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. Quando a consulta é executada, ela retorna um erro com definições de padrão ausentes:

map_ip_to_longlat("10.10.10.10")

Declarar e definir um padrão

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. Assim, ele precede a consulta do usuário com uma declaração de padrão de map_ip_to_longlat vazia 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 detetadas: ["map_ip_to_longlat('10.10.10.10')"]

Invocar um padrão

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 procurar os dados de enriquecimento em 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 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.

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

Output