Instrucción Pattern

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

Un patrón es una construcción que asigna tuplas de cadena a expresiones tabulares.

Cada patrón debe declarar un nombre de patrón y, opcionalmente, definir una asignación de patrones. Los patrones que definen una asignación devuelven una expresión tabular cuando se invoca. Separe las dos instrucciones por punto y coma.

Los patrones vacíos son patrones declarados pero que no definen una asignación. Cuando se invoca, devuelven SEM0036 de error junto con los detalles de las definiciones de patrón que faltan en el encabezado HTTP.

Las aplicaciones de nivel intermedio que proporcionan una experiencia de lenguaje de consulta kusto (KQL) pueden usar los detalles devueltos como parte de su proceso para enriquecer los resultados de la consulta KQL. Para obtener más información, consulte Trabajar con aplicaciones de nivel intermedio.

Sintaxis

• Declarar un patrón vacío:

  declare pattern patternName;

• Declare y defina un patrón:

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

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expression1};

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

  } ;

• Invoque un patrón:

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

Obtenga más información sobre las convenciones de sintaxis de .

Parámetros

Ejemplos

Los ejemplos de esta sección muestran cómo usar la sintaxis para ayudarle a empezar.

Definición de un patrón simple

En este ejemplo se define un patrón que asigna estados a una expresión que devuelve su capital o ciudad 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 salida

Definición de un patrón con ámbito

En este ejemplo se define un patrón para definir el ámbito de los datos y las métricas de los datos de la aplicación. El patrón se invoca para devolver una unión de los datos.

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 salida

Normalización

Hay variaciones de sintaxis para invocar patrones. Por ejemplo, la unión siguiente devuelve una expresión de patrón única, ya que todas las invocaciones son del mismo patrón.

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

Sin caracteres comodín

No hay ningún tratamiento especial dado a los caracteres comodín en un patrón. Por ejemplo, la consulta siguiente devuelve una única invocación de patrón que falta.

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

error semántico de salida

No se declararon una o más referencias de patrón. Referencias de patrón detectadas: ["app('ApplicationX').[' *']"]

Trabajar con aplicaciones de nivel intermedio

Una aplicación de nivel intermedio proporciona a sus usuarios la capacidad de usar KQL y quiere mejorar la experiencia enriqueciendo los resultados de la consulta con datos aumentados de su servicio interno.

Para ello, la aplicación proporciona a los usuarios una instrucción pattern que devuelve datos tabulares que sus usuarios pueden usar en sus consultas. Los argumentos del patrón son las claves que usará la aplicación para recuperar los datos de enriquecimiento.

Cuando el usuario ejecuta la consulta, la aplicación no analiza la propia consulta, sino que usa el error devuelto por un patrón vacío para recuperar las claves que requiere. Por lo tanto, antepone la consulta con la declaración de patrón vacía, la envía al clúster para su procesamiento y, a continuación, analiza el encabezado HTTP devuelto para recuperar los valores de los argumentos de patrón que faltan. La aplicación usa estos valores para buscar los datos de enriquecimiento y crea una nueva declaración que define la asignación de datos de enriquecimiento adecuada.

Por último, la aplicación antepone la nueva definición a la consulta, la reenvía para su procesamiento y devuelve el resultado que recibe al usuario.

Ejemplo

En los ejemplos, se declara, define un patrón y, a continuación, se invoca.

Declarar un patrón vacío

En este ejemplo, una aplicación de nivel intermedio enriquece las consultas con ubicaciones de longitud y latitud. La aplicación usa un servicio interno para asignar direcciones IP a ubicaciones de longitud y latitud y proporciona un patrón denominado map_ip_to_longlat. Cuando se ejecuta la consulta, devuelve un error con definiciones de patrón que faltan:

map_ip_to_longlat("10.10.10.10")

Declarar y definir un patrón

La aplicación no analiza esta consulta y, por tanto, no sabe qué dirección IP (10.10.10.10) se pasó al patrón. Por lo tanto, antepone la consulta de usuario con una declaración de patrón de map_ip_to_longlat vacía y la envía para su procesamiento:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

La aplicación recibe el siguiente error en respuesta.

No se declararon una o más referencias de patrón. Referencias de patrón detectadas: ["map_ip_to_longlat('10.10.10.10')"]

Invocación de un patrón

La aplicación inspecciona el error, determina que el error indica una referencia de patrón que falta y recupera la dirección IP que falta (10.10.10.10.10). Usa la dirección IP para buscar los datos de enriquecimiento en su servicio interno y crea un nuevo patrón que define la asignación de la dirección IP a los datos de longitud y latitud correspondientes. El nuevo patrón se antepone a la consulta del usuario y se vuelve a ejecutar.

Esta vez la consulta se realiza correctamente porque los datos de enriquecimiento ahora se declaran en la consulta y el resultado se envía al usuario.

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 salida