Compartir a través de

Convenciones de sintaxis para la documentación de referencia

Cambie los servicios mediante la lista desplegable Versión . Más información sobre la navegación.
Se aplica a: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

En este artículo se describen las convenciones de sintaxis seguidas en la documentación de referencia de comandos de administración y lenguaje de consulta kusto (KQL).

Un buen lugar para empezar a aprender el lenguaje de consulta kusto es comprender la estructura de consulta general. Lo primero que observa al examinar una consulta de Kusto es el uso del símbolo de canalización (|). La estructura de una consulta de Kusto comienza por obtener los datos de un origen de datos y, a continuación, pasar los datos a través de una canalización, y cada paso proporciona algún nivel de procesamiento y, a continuación, pasa los datos al paso siguiente. Al final de la canalización, obtendrá el resultado final. En efecto, esta es nuestra canalización:

Get Data | Filter | Summarize | Sort | Select

Este concepto de pasar datos hacia abajo por la canalización permite una estructura intuitiva, ya que es fácil crear una imagen mental de los datos en cada paso.

Para ilustrar esto, echemos un vistazo a la siguiente consulta, que examina los registros de inicio de sesión de Microsoft Entra. A medida que lee cada línea, puede ver las palabras clave que indican lo que sucede con los datos. Hemos incluido la fase pertinente en la canalización como comentario en cada línea.

Nota:

Puede agregar comentarios a cualquier línea de una consulta si las precede con una barra diagonal doble (//).

SigninLogs                              // Get data
| evaluate bag_unpack(LocationDetails)  // Ignore this line for now; we'll come back to it at the end.
| where RiskLevelDuringSignIn == 'none' // Filter
   and TimeGenerated >= ago(7d)         // Filter
| summarize Count = count() by city     // Summarize
| sort by Count desc                    // Sort
| take 5                                // Select

Dado que la salida de cada paso actúa como entrada para el paso siguiente, el orden de los pasos puede determinar los resultados de la consulta y afectar a su rendimiento. Es fundamental que ordene los pasos según lo que desea salir de la consulta.

Sugerencia

  • Una buena regla general es filtrar los datos al principio, por lo que solo se pasan los datos pertinentes por la canalización. Esto aumenta considerablemente el rendimiento y garantiza que no se incluyen accidentalmente datos irrelevantes en los pasos de resumen.
  • En este artículo se indican algunos otros procedimientos recomendados que se deben tener en cuenta. Para obtener una lista más completa, consulte Procedimientos recomendados de consulta.

Convenciones de sintaxis

Convención Description
Block Literales de cadena que se van a escribir exactamente como se muestra.
Italic Parámetros que se van a proporcionar un valor al usar la función o el comando.
[ ] Indica que el elemento incluido es opcional.
( ) Indica que se requiere al menos uno de los elementos incluidos.
| (canalización) Se usa entre corchetes o redondos para indicar que puede especificar uno de los elementos separados por el carácter de canalización. En este formato, la canalización es equivalente al operador OR lógico. Cuando se encuentra en un bloque (|), la canalización forma parte de la sintaxis de consulta KQL.
[, ...] Indica que el parámetro anterior se puede repetir varias veces, separados por comas.
; Terminador de instrucción de consulta.

Examples

Función escalar

En este ejemplo se muestra la sintaxis y un uso de ejemplo de la función hash, seguida de una explicación de cómo se traduce cada componente de sintaxis en el uso de ejemplo.

Syntax

hash( source [,mod])

Ejemplo de uso

hash("World")
  • El nombre de la función, hashy el paréntesis de apertura se escriben exactamente como se muestra.
  • "World" se pasa como argumento para el parámetro de origen necesario.
  • No se pasa ningún argumento para el parámetro mod , que es opcional como se indica en los corchetes.
  • El paréntesis de cierre se escribe exactamente como se muestra.

Operador tabular

En este ejemplo se muestra la sintaxis y un uso de ejemplo del operador sort, seguido de una explicación de cómo se traduce cada componente de sintaxis en el uso de ejemplo.

Syntax

T| sort bycolumn [] [asc | descnulls first | nulls last] [, ...]

Ejemplo de uso

StormEvents
| sort by State asc, StartTime desc
  • La tabla StormEvents se pasa como argumento para el parámetro T necesario.
  • | sort by se especifica exactamente como se muestra. En este caso, el carácter de canalización forma parte de la sintaxis de la instrucción de expresión tabular , tal como se representa mediante el texto de bloque. Para más información, consulte ¿Qué es una instrucción de consulta?
  • La columna Estado se pasa como argumento para el parámetro de columna necesario con la marca opcional asc .
  • Después de una coma, se pasa otro conjunto de argumentos: la columna StartTime con la marca opcional desc . La sintaxis [, ...] indica que se pueden pasar más conjuntos de argumentos, pero no son necesarios.

Trabajar con parámetros opcionales

Para proporcionar un argumento para un parámetro opcional que viene después de otro parámetro opcional, debe proporcionar un argumento para el parámetro anterior. Este requisito se debe a que los argumentos deben seguir el orden especificado en la sintaxis. Si no tiene un valor específico para pasar para el parámetro, use un valor vacío del mismo tipo.

Ejemplo de parámetros opcionales secuenciales

Tenga en cuenta la sintaxis del complemento http_request:

evaluate http_request ( Uri [,RequestHeaders [,Options]] )

RequestHeaders y Options son parámetros opcionales de tipo dinámico. Para proporcionar un argumento para el parámetro Options , también debe proporcionar un argumento para el parámetro RequestHeaders . En el ejemplo siguiente se muestra cómo proporcionar un valor vacío para el primer parámetro opcional, RequestHeaders, para poder especificar un valor para el segundo parámetro opcional, Options.

evaluate http_request ( "https://contoso.com/", dynamic({}), dynamic({ EmployeeName: Nicole }) )

Contenido relacionado

  • Last updated on