Instrucción Pattern

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. Las instrucciones deben estar separadas por un punto y coma.

Los patrones vacíos son patrones declarados pero que no definen una asignación. Cuando se invoca, devuelven el error SEM0036 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.

Syntax

• Declare un patrón vacío:

  declarepatternPatternName;

• Declare y defina un patrón:

  declarepatternPatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

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

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

  } ;

• Invocación de un patrón:

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

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

Parámetros

Nombre	Tipo	Requerido	Descripción
PatternName	string	✔️	Nombre del patrón.
ArgName	string	✔️	El nombre del argumento. Los patrones pueden tener uno o varios argumentos.
ArgType	string	✔️	El tipo de datos escalar del argumento ArgName . Valores posibles: string
PathName	string		Nombre del argumento path. Los patrones no pueden tener ninguna ruta de acceso ni una ruta de acceso.
PathArgType	string		Tipo del argumento PathArgType . Valores posibles: string
ArgValue	string	✔️	Los valores de tupla ArgName y PathName opcionales que se asignarán a una expresión.
PathValue	string		Valor que se va a asignar para PathName.
expression	string	✔️	Expresión tabular o lambda que hace referencia a una función que devuelve datos tabulares. Por ejemplo: Logs | where Timestamp > ago(1h)

Ejemplos

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

Definición de patrones simples

En el ejemplo siguiente se define un patrón que asigna estados a una expresión que devuelve su capital o ciudad principal.

Ejecución de la 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

Salida

Capital
Edmonton

Ejecución de la consulta

En el ejemplo siguiente se define un patrón que define algunos datos de aplicación con ámbito.

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

Salida

Aplicación	data	Métricas
Aplicación n.º 2	9
Aplicación n.º 2	8
Aplicación n.º 2	7
Aplicación n.º 2	6
Aplicación n.º 2	5
Aplicación n.º 1		0.53674122855537532
Aplicación n.º 1		0.78304713305654439
Aplicación n.º 1		0.20168860732346555
Aplicación n.º 1		0.13249123867679469
Aplicación n.º 1		0.19388305330563443

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 tienen el 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 sola 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

Devuelve un error semántico.

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 de patrón 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 planea aprovechar 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 del usuario, la reenvía para su procesamiento y devuelve el resultado que recibe al usuario.

Ejemplo

En el ejemplo siguiente, una aplicación de nivel intermedio proporciona la capacidad de enriquecer 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 para este fin. Supongamos que la aplicación obtiene la siguiente consulta del usuario:

map_ip_to_longlat("10.10.10.10")

La aplicación no analiza esta consulta y, por tanto, no sabe qué dirección IP (10.10.10.10.10) se pasó al patrón. Por lo tanto, antepone la consulta de usuario con una declaración de patrón vacía map_ip_to_longlat 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')"]

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.

Ejecución de la 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")

Salida

Lat	Long
37.405992	-122.078515

Esta funcionalidad no se admite en Azure Monitor.