Parámetros de la lista desplegable del libro

Mediante el uso de parámetros desplegables, puede recopilar uno o varios valores de entrada de un conjunto conocido. Por ejemplo, puedes usar un parámetro desplegable para seleccionar una de las solicitudes de la aplicación. Los parámetros desplegables también proporcionan una forma fácil de recoger entradas arbitrarias de los usuarios. Los parámetros desplegables son especialmente útiles para permitir el filtrado en sus informes interactivos.

La forma más sencilla de especificar un parámetro desplegable es proporcionando una lista estática en la configuración del parámetro. Una manera más interesante es obtener la lista dinámicamente a través de una consulta de KQL. También puede especificar si es una o varias selecciones mediante la configuración de parámetros. Si es de selección múltiple, puede especificar cómo se debe dar formato al conjunto de resultados, por ejemplo, como delimitador o comillas.

Componentes de parámetros desplegables

Al usar contenido JSON estático o obtener valores dinámicos de consultas, los parámetros desplegables permiten hasta cuatro campos de información, en este orden específico:

1. value (obligatorio): la primera columna o campo de los datos se usa como valor literal del parámetro. En el caso de parámetros JSON estáticos simples, puede ser tan sencillo como el contenido JSON ["dev", "test", "prod"], que crearía una lista desplegable de tres elementos con esos valores como el valor y la etiqueta en la lista desplegable. El nombre de este campo no necesita ser value, la lista desplegable usará el primer campo de los datos independientemente del nombre.

2. label (opcional): la segunda columna o campo de los datos se usa como nombre para mostrar o etiqueta del parámetro en la lista desplegable. Si no se especifica, el valor se usa como etiqueta. El nombre de este campo no necesita ser label, la lista desplegable usará el segundo campo de los datos independientemente del nombre.

3. selected (opcional): la tercera columna o campo de los datos se usa para especificar qué valor se debe seleccionar de forma predeterminada. Si no se especifica, no se selecciona ningún elemento de forma predeterminada. El comportamiento de selección se basa en el concepto "falsy" de JavaScript, por lo que los valores como 0, false, null, o cadenas vacías se tratan como no seleccionadas. El nombre de este campo no necesita ser selected, la lista desplegable usará el tercer campo de los datos independientemente del nombre.

   Nota:

   Esto solo controla la selección predeterminada, una vez que un usuario ha seleccionado valores en la lista desplegable, se usan esos valores seleccionados por el usuario. Incluso si se ejecuta una consulta posterior para el parámetro y devuelve nuevos valores predeterminados. Para volver a la selección predeterminada, el uso puede usar la opción "Elementos predeterminados" en la lista desplegable, que volverá a consultar los valores predeterminados y los aplicará.

   Los valores predeterminados solo se aplican si el usuario no ha seleccionado ningún elemento.

   Si una consulta posterior devuelve elementos que no incluyen valores seleccionados previamente, los valores que faltan se quitan de la selección. Los elementos seleccionados de la lista desplegable se convertirán en la intersección de los elementos devueltos por la consulta y los elementos seleccionados anteriormente.

4. group (opcional): a diferencia de los demás campos, la columna de agrupación debe denominarse group y aparecer después de value, label y selected. Este campo de los datos se usa para agrupar los elementos de la lista desplegable. Si no se especifica, no se usa ninguna agrupación. Si no es necesaria la selección predeterminada, los datos o consultas deben devolver un campo de selected en al menos un objeto o fila, incluso si todos los valores son false.

Nota:

El parámetro desplegable omite cualquier otro campo de los datos. Se recomienda limitar el contenido a solo los campos usados por la lista desplegable para evitar que las consultas complicadas devuelvan datos que se omiten.

Creación de un parámetro desplegable estático

1. Comience con un libro vacío en modo de edición.

2. Seleccione Agregar parámetros>Agregar parámetro.

3. En el panel de nuevo parámetro que se abre, escriba:

   1. Nombre del parámetro: Environment

   2. Tipo de parámetro: Drop down

   3. Obligatorio: checked

   4. Permitir selecciones múltiples: unchecked

   5. Obtener datos de: JSON o, seleccione Query y seleccione el origen de datos JSON.

      El origen de datos JSON permite que el contenido JSON haga referencia a cualquier parámetro existente.

4. En el bloque de texto de entrada JSON, inserte este fragmento de código JSON:

   [
       { "value":"dev", "label":"Development" },
       { "value":"ppe", "label":"Pre-production" },
       { "value":"prod", "label":"Production", "selected":true }
   ]
   

5. Seleccione Actualizar.

6. Seleccione Guardar para crear el parámetro.

7. El parámetro Entorno es una lista desplegable con los tres valores.

   

Creación de una lista desplegable estática con grupos de elementos

Si el resultado de su consulta/JSON contiene un campo group, la lista desplegable muestra grupos de valores. Siga el ejemplo anterior, pero use el siguiente JSON en su lugar:

[
    { "value":"dev", "label":"Development", "group":"Development" },
    { "value":"dev-cloud", "label":"Development (Cloud)", "group":"Development" },
    { "value":"ppe", "label":"Pre-production", "group":"Test" },
    { "value":"ppe-test", "label":"Pre-production (Test)", "group":"Test" },
    { "value":"prod1", "label":"Prod 1", "selected":true, "group":"Production" },
    { "value":"prod2", "label":"Prod 2", "group":"Production" }
]

Nota:

Al usar un campo group en la consulta, también debe proporcionar un valor para los campos label y selected.

Creación de un parámetro desplegable dinámico

1. Comience con un libro vacío en modo de edición.

2. Seleccione Agregar parámetros>Agregar parámetro.

3. En el panel de nuevo parámetro que se abre, escriba:

   1. Nombre del parámetro: RequestName
   2. Tipo de parámetro: Drop down
   3. Obligatorio: checked
   4. Permitir selecciones múltiples: unchecked
   5. Obtener datos de: Query

4. En el bloque de texto de entrada JSON, inserte este fragmento de código JSON:

       requests
       | summarize by name
       | order by name asc
   

5. Seleccione Ejecutar consulta.

6. Seleccione Guardar para crear el parámetro.

7. El parámetro RequestName es una lista desplegable con los nombres de todas las solicitudes de la aplicación.

   

Ejemplo: Etiquetas personalizadas, selección del primer elemento de forma predeterminada y agrupación por nombre de operación

La consulta usada en el parámetro desplegable dinámico anterior devuelve una lista de valores que se representan en la lista desplegable. Si desea un nombre para mostrar diferente o permitir que el usuario seleccione el nombre para mostrar, use el valor, la etiqueta, la selección y las columnas de grupo.

En el ejemplo siguiente se muestra cómo obtener una lista de distintas dependencias de Application Insights. Los nombres para mostrar tienen un estilo con un emoji, el primer elemento se selecciona de forma predeterminada y los elementos se agrupan por nombres de operación:

dependencies
| summarize by operation_Name, name
| where name !contains ('.')
| order by name asc
| serialize Rank = row_number()
| project value = name, label = strcat('🌐 ', name), selected = iff(Rank == 1, true, false), group = operation_Name

Hacer referencia a un parámetro desplegable

Puede hacer referencia a parámetros desplegables en cualquier lugar donde se puedan usar los parámetros, incluida la sustitución del valor del parámetro en consultas, configuración de visualización, contenido de texto de Markdown u otros lugares donde puede seleccionar un parámetro como una opción.

En KQL

1. Seleccione Agregar consulta para agregar un control de consulta y, a continuación, seleccione un recurso de Application Insights.

2. En el editor de KQL, escriba este fragmento de código:

       requests
       | where name == '{RequestName}'
       | summarize Requests = count() by bin(timestamp, 1h)
   
   

3. El fragmento amplía el tiempo de evaluación de la consulta a:

       requests
       | where name == 'GET Home/Index'
       | summarize Requests = count() by bin(timestamp, 1h)
   

4. Seleccione la Ejecución de una consulta para ver los resultados. También se puede representar como un gráfico.

   

Opciones de parámetros desplegables

Parámetro	Descripción	Ejemplo
{DependencyName}	El valor seleccionado	GET fabrikamaccount
{DependencyName:value}	Valor seleccionado (igual que el anterior)	GET fabrikamaccount
{DependencyName:label}	La etiqueta seleccionada	🌐 GET fabrikamaccount
{DependencyName:escape}	Valor seleccionado, con los caracteres de comillas comunes reemplazados cuando se da formato a las consultas	GET fabrikamaccount

Selección múltiple

Hasta ahora, los ejemplos establecen explícitamente el parámetro para seleccionar solo un valor de la lista desplegable. Los parámetros desplegables también admiten varias selecciones. Para habilitar esta opción, active la casilla Permitir varias selecciones.

Puede especificar el formato del conjunto de resultados a través del delimitador y la cita con la configuración. De forma predeterminada, se usa , (coma) como delimitador y se usa ' (comillas simples) como carácter de comilla. El valor predeterminado devuelve los valores como una colección en forma de 'a', 'b', 'c' cuando se da formato a la consulta. También puede limitar el número máximo de selecciones.

Al usar un parámetro de selección múltiple en una consulta, asegúrese de que el KQL que hace referencia al parámetro funciona con el formato del resultado. Por ejemplo:

• Un parámetro de valor único no incluye comillas cuando se da formato a una consulta, por lo que asegúrese de incluir las comillas en la propia consulta, por ejemplo: where name == '{parameter}'.
• Las comillas se incluyen en el parámetro con formato cuando se usa un parámetro de selección múltiple, por lo que debe asegurarse de que la consulta no incluye comillas. Por ejemplo, where name in ({parameter}).

Observe cómo este ejemplo también cambió de name == a name in. El operador == solo permite un valor único, mientras que el operador in permite varios valores.

dependencies
| where name in ({DependencyName})
| summarize Requests = count() by bin(timestamp, 1h), name

En este ejemplo se muestra el parámetro desplegable de selección múltiple en el trabajo:

Selecciones especiales desplegables

Los parámetros desplegables también permiten especificar valores especiales que también aparecen en la lista desplegable:

• Uno cualquiera
• Tres cualquiera
• ...
• 100 cualquiera
• Cualquier límite personalizado
• Todo

Cuando se seleccionan estos elementos especiales, el valor del parámetro se establece automáticamente en el número específico de elementos o en todos los valores.

Mayúsculas y minúsculas especiales, y permitir que una selección vacía se trate como Todo

Al seleccionar Todos, aparece un campo adicional, que permite especificar un valor especial para el parámetro Todos. Esto resulta útil cuando "Todos" podría ser un gran número de elementos y podría generar una consulta muy grande.

En este caso específico, la cadena [] se usa en lugar de un valor. Esta cadena se puede usar para generar una matriz vacía en la consulta de registros, como:

let selection = dynamic([{Selection}]);
SomeQuery 
| where array_length(selection) == 0 or SomeField in (selection)

Si se seleccionan todos los elementos, el valor de Selection es [], lo que produce una matriz vacía para la variable selection de la consulta. Si no se selecciona ningún valor, el valor de Selection tiene el formato de cadena vacía, lo que también da como resultado una matriz vacía. Si se selecciona algún valor, se les da formato dentro de la parte dinámica de la consulta, lo que hace que la matriz tenga esos valores. Después puede probar array_length de 0 para que no se aplique el filtro o usar el operador in para filtrar sobre los valores de la matriz.

Otros ejemplos comunes usan "*" como valor marcador especial cuando se requiere un parámetro y después prueban con:

| where "*" in ({Selection}) or SomeField in ({Selection})

Pasos siguientes

Obtenga información sobre los tipos de visualizaciones que puede usar para crear informes visuales enriquecidos con libros de Azure.