Uso de funciones en consultas de registros de Azure Monitor
Una función es una consulta de registro en Azure Monitor que se puede usar en otras consultas de registro como si se tratase de un comando. Puede utilizar funciones para proporcionar soluciones a distintos clientes, además de reutilizar la lógica de consulta en su propio entorno. En este artículo se describe cómo usar funciones y cómo crear las suyas propias.
Permisos necesarios
| Acción | Permisos requeridos |
|---|---|
| Visualización o uso de funciones | Los permisos Microsoft.OperationalInsights/workspaces/query/*/read del área de trabajo de Log Analytics, como los que proporciona el rol integrado de lector de Log Analytics, por ejemplo. |
| Creación o edición de funciones | Los permisos microsoft.operationalinsights/workspaces/savedSearches/write del área de trabajo de Log Analytics, según lo proporcionado por el rol integrado de colaborador de Log Analytics, por ejemplo. |
Tipos de funciones
Hay dos tipos de funciones en Azure Monitor:
Funciones de solución: Las funciones precompiladas se incluyen con Azure Monitor. Estas funciones están disponibles en todas las áreas de trabajo de Log Analytics y no se pueden modificar.
Funciones del área de trabajo: estas funciones se instalan en un área de trabajo de Log Analytics determinada. El usuario puede modificarlas y controlarlas.
Funciones de vista
Puede ver las funciones de solución y las funciones del área de trabajo en el área de trabajo actual en la pestaña Funciones del panel izquierdo de un área de trabajo de Log Analytics. Use Filtro para filtrar las funciones incluidas en la lista. Use Agrupar por para cambiar la agrupación. Escriba una cadena en el cuadro Buscar para buscar una función determinada. Mantenga el puntero sobre una función para ver más detalles sobre ella, incluida una descripción y parámetros.
Uso de una función
Use una función en una consulta escribiendo su nombre con valores para cualquier parámetro igual que lo haría en un comando. La salida de la función se puede devolver como resultados o canalizarse a otro comando.
Para agregar una función a la consulta actual, haga doble clic en su nombre o mantenga el puntero sobre ella y seleccione Usar en el editor. Las funciones del área de trabajo también se incluirán en IntelliSense a medida que escriba una consulta.
Si una consulta requiere parámetros, puede proporcionarlos mediante la sintaxis function_name(param1,param2,...).
Creación de una función
Para crear una función a partir de la consulta actual del editor, seleccione Guardar>Guardar como función.
Para crear una función con Log Analytics en Azure Portal, seleccione Guardar y, después, proporcione la información de la tabla siguiente:
| Configuración | Descripción |
|---|---|
| Nombre de la función | El nombre de la función. El nombre no puede incluir ningún espacio o carácter especial. Tampoco puede comenzar con un carácter de subrayado (_), ya que este carácter está reservado para las funciones de solución. |
| Categoría heredada | Categoría definida por el usuario para ayudar a filtrar y agrupar funciones. |
| Guardar como grupo de equipos | Guarde la consulta como un grupo de equipos. |
| Parámetros | Agregue un parámetro para cada variable de la función que requiera un valor cuando se utilice. Para obtener más información, consulte Parámetros de función. |
Parámetros de función
Puede agregar parámetros a una función para que pueda proporcionar valores de determinadas variables al llamarla. Esto permite usar la misma función en consultas diferentes, cada una de las cuales proporciona valores diferentes para los parámetros. Los parámetros se definen mediante las siguientes propiedades:
| Configuración | Descripción |
|---|---|
| Tipo | Tipo de datos para el valor. |
| Nombre | Nombre del parámetro. Este nombre debe usarse en la consulta para reemplazar por el valor del parámetro. |
| Valor predeterminado | Valor que se usará para el parámetro si no se proporciona ningún valor. |
Los parámetros se ordenan a medida que se crean. Primero aparecen los parámetros sin ningún valor predeterminado y, después, aquellos que sí lo tienen.
Uso del código de función
Puede ver el código de una función para obtener información sobre cómo funciona o para modificar el código de una función del área de trabajo. Seleccione Cargar el código de la función para agregar el código de la función a la consulta actual del editor.
Si agrega el código de función a una consulta vacía o a la primera línea de una consulta existente, se agregará el nombre de función a la pestaña. Una función del área de trabajo, permite editar los detalles de la función.
Edición de una función
Edite las propiedades o el código de una función creando una nueva consulta. Mantenga el puntero sobre el nombre de la función y seleccione Cargar código de función. Realice las modificaciones que desee en el código y seleccione Guardar. A continuación, seleccione Editar detalles de la función. Realice los cambios que desee en las propiedades y parámetros de la función y seleccione Guardar.
Ejemplo
La siguiente función de ejemplo devuelve todos los eventos del registro de actividades de Azure a partir de una fecha determinada y los eventos que coinciden con una categoría determinada.
Comience con la consulta siguiente mediante el uso de valores codificados de forma rígida para comprobar que la consulta funciona según lo previsto.
AzureActivity
| where CategoryValue == "Administrative"
| where TimeGenerated > todatetime("2021/04/05 5:40:01.032 PM")
A continuación, reemplace los valores codificados de forma rígida por nombres de parámetro. A continuación, guarde la función seleccionando Guardar>Guardar como función.
AzureActivity
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam
Proporcione los siguientes valores para las propiedades de función:
| Propiedad | Value |
|---|---|
| Nombre de función | AzureActivityByCategory |
| Categoría heredada | Funciones de demostración |
Defina los parámetros siguientes antes de guardar la función:
| Tipo | Nombre | Valor predeterminado |
|---|---|---|
| string | CategoryParam | "Administrativa" |
| datetime | DateParam |
Cree una nueva consulta y mantenga el puntero sobre ella para ver la nueva función. Examine el orden de los parámetros. Deben especificarse en este orden cuando se usa la función.
Seleccione Usar en el editor para agregar la nueva función a una consulta. A continuación, agregue valores para los parámetros. No es necesario especificar un valor para CategoryParam porque tiene un valor predeterminado.
Pasos siguientes
Consulte Operaciones de cadena para más información sobre cómo escribir consultas de registro de Azure Monitor.