Instrução PATTERN

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 chamados. 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 SEM0036 de erro junto 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:

  declarepattern Nome do Padrão ;

• Declare e defina um padrão:

  declarepattern Nome do Padrão = (ArgName : ArgType [, ... ]) [ [ Nome do Caminho : PathArgType ] ]

  {

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

      ( [ ArgValue1_2 [ , ArgValue2_2, ... ] ) .[ [ PathValue_2 ] ] = { expressão2 } ; ... ]

  } ;

• Invocar um padrão:

  • PatternName ( ArgValue1 [ , ArgValue2 ...] ).Valor do caminho
  • PatternName ( ArgValue1 [ , ArgValue2 ...] ).["Valor do caminho"]

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
Nome do Padrão	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 escalares do argumento ArgName . Valores possíveis: string
PathName	string		O nome do argumento de caminho. Os padrões não podem ter 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.
Valor do caminho	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, em seguida, chamado.

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 aos 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 a seus 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 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 planeja aproveitar o erro retornado por um padrão vazio para recuperar as chaves necessárias. Portanto, ele precede 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 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. Por fim, o aplicativo anexa a nova definição à consulta do usuário, reenvia-a para processamento e retorna o resultado recebido 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 receba 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 precede 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 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.

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