Pattern statement

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

A pattern is a construct that maps string tuples to tabular expressions.

Each pattern must declare a pattern name and optionally define a pattern mapping. 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. When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

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.

Syntax

• 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] ] ={expression1};

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

  } ;

• Invocar um padrão:

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

Learn more about syntax conventions.

Parameters

Examples

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

Output

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

Output

Normalization

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

No wildcards

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.

Example

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

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. 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

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (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")

Output