Instrução Pattern

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

Um padrão é um constructo que mapeia tuplas de cadeia de caracteres para expressões tabulares.

Cada padrão deve declarar um nome 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 as duas instruções 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 junto 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 KQL (Linguagem de Consulta Kusto) 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] ] ={expressão2};... ]

  } ;

• Invocar um padrão:

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

Saiba mais sobre convenções de sintaxe.

Parâmetros

Exemplos

Os exemplos nesta seção mostram como usar a sintaxe para ajudá-lo a começar.

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

de saída

Definir um padrão com escopo

Este exemplo define um padrão para definir o escopo de dados e métricas dos dados do aplicativo. 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

de saída

Normalização

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

de erro semântico de saída

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 KQL e deseja aprimorar 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 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. Portanto, ele prepara a consulta com a declaração de padrão vazia, envia-a ao 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 anexa a nova definição à consulta, a reenvia para processamento e retorna o resultado recebido ao usuário.

Exemplo

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

Declarar um padrão vazio

Neste exemplo, um aplicativo de camada intermediária enriquece 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. Portanto, ele anexa a consulta de 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 detectadas: ["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.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.

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

de saída