Compartir a través de


Parámetros de libro

Al usar parámetros, puede recopilar entradas de los usuarios y hacer referencia a estas en otras partes del libro. Normalmente se usa para definir el ámbito del conjunto de resultados o establecer el objeto visual correcto. Puede crear informes interactivos y experiencias mediante esta funcionalidad clave.

Al usar libros, puede controlar cómo se presentan los controles de parámetro a los consumidores. Pueden ser cuadros de texto frente a listas desplegables, selección única frente a selección múltiple, y valores de texto, JSON, KQL o Azure Resource Graph.

Entre los tipos de parámetros admitidos se incluyen:

  • Tiempo: le permite seleccionar entre intervalos de tiempo rellenados previamente o seleccionar un intervalo personalizado.
  • Lista desplegable: le permite seleccionar entre un valor o un conjunto de valores.
  • Grupo de opciones: le permite seleccionar un valor de un conjunto conocido.
  • Texto: le permite escribir texto arbitrario.
  • Criterios: le permite definir un conjunto de criterios basados en parámetros previamente especificados, que se evaluarán para proporcionar un valor dinámico.
  • Recurso: le permite seleccionar uno o varios recursos de Azure.
  • Suscripción: le permite seleccionar uno o varios recursos de suscripción de Azure.
  • Multivalor: le permite establecer uno o varios valores de texto arbitrarios.
  • Tipo de recurso: le permite seleccionar uno o varios valores de tipo de recurso de Azure.
  • Ubicación: le permite seleccionar uno o varios valores de ubicación de Azure.

Referencia a un parámetro

Puede hacer referencia a los valores de parámetros de otras partes de los libros mediante enlaces o expansiones de valores.

Referencia a un parámetro con enlaces

En este ejemplo, se muestra cómo hacer referencia a un parámetro de intervalo de tiempo con enlaces:

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

  2. Abra la lista desplegable Intervalo de tiempo y seleccione la opción Intervalo de tiempo en la sección Parámetros de la parte inferior:

    • Esta acción enlaza el parámetro de intervalo de tiempo con el intervalo de tiempo del gráfico.
    • El ámbito de tiempo de la consulta de ejemplo es ahora Últimas 24 horas.
  3. Ejecute la consulta para ver los resultados.

    Captura de pantalla que muestra un parámetro de intervalo de tiempo al que se hace referencia mediante enlaces.

Referencia a un parámetro con KQL

En este ejemplo se muestra cómo hacer referencia a un parámetro de intervalo de tiempo con KQL:

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

  2. En KQL, escriba un filtro de ámbito de tiempo mediante el parámetro: | where timestamp {TimeRange}.

    • Este parámetro amplía el tiempo de evaluación de la consulta a | where timestamp > ago(1d).
    • Esta opción es el valor del intervalo de tiempo del parámetro.
  3. Ejecute la consulta para ver los resultados.

    Captura de pantalla que muestra un intervalo de tiempo al que se hace referencia en la consulta de KQL.

Referencia a un parámetro con texto

En este ejemplo, se muestra cómo hacer referencia a un parámetro de intervalo de tiempo con texto:

  1. Agregue un control de texto al libro.
  2. En Markdown, escriba The chosen time range is {TimeRange:label}.
  3. Seleccione Edición finalizada.
  4. El control de texto muestra el texto: El intervalo de tiempo elegido es Últimas 24 horas

Opciones de formato de parámetros

Cada tipo de parámetro tiene sus propias opciones de formato. Use la sección Vistas previas del panel Editar parámetro para ver las opciones de expansión de aplicación de formato del parámetro.

Imagen que muestra las opciones de un parámetro de intervalo de tiempo.

Puede usar estas opciones para dar formato a todos los tipos de parámetros, excepto para el Selector de intervalo de tiempo. Para obtener ejemplos de tiempos de aplicación de formato, consulte Opciones de parámetros temporal.

Entre los tipos de parámetros se incluyen:

  • Selector de recursos: se da formato a los identificadores de los recursos.
  • Selector de suscripciones: se da formato a los valores de las suscripciones.

Conversión de toml a json

Sintaxis: {param:tomltojson}

Valor original:

name = "Sam Green"

[address]
state = "New York"
country = "USA"

Valor formateado:

{
  "name": "Sam Green",
  "address": {
    "state": "New York",
    "country": "USA"
  }
}

Aplicación de caracteres de escape a JSON

Sintaxis: {param:escapejson}

Valor original:

{
	"name": "Sam Green",
	"address": {
		"state": "New York",
		"country": "USA"
  }
}

Valor formateado:

{\r\n\t\"name\": \"Sam Green\",\r\n\t\"address\": {\r\n\t\t\"state\": \"New York\",\r\n\t\t\"country\": \"USA\"\r\n  }\r\n}

Codificación de texto en base64

Sintaxis: {param:base64}

Valor original:

Sample text to test base64 encoding

Valor formateado:

U2FtcGxlIHRleHQgdG8gdGVzdCBiYXNlNjQgZW5jb2Rpbmc=

Aplicación de formato a los parámetros mediante JSONPath

En el caso de los parámetros de cadena que son contenido JSON, puede usar JSONPath en la cadena de formato de parámetro.

Por ejemplo, puede tener un parámetro de cadena denominado selection que era el resultado de una consulta o selección en una visualización que tenga el siguiente valor:

{ "series":"Failures", "x": 5, "y": 10 }

Con JSONPath, puede obtener valores individuales de ese objeto:

Formato Resultado
{selection:$.series} Failures
{selection:$.x} 5
{selection:$.y} 10

Nota

Si el valor del parámetro no es JSON válido, el resultado del formato será un valor vacío.

Estilo del parámetro

Los siguientes estilos están disponibles para los parámetros.

Píldoras

El estilo de las píldoras es el estilo predeterminado. Los parámetros tienen aspecto de texto y requieren que el usuario los seleccione una vez para entrar en el modo de edición.

Captura de pantalla que muestra el modo de lectura de píldoras de Libros de Azure.

Captura de pantalla que muestra el modo de edición de píldoras de Libros de Azure.

Estándar

En el estilo estándar, los controles siempre son visibles, con una etiqueta encima del control.

Captura de pantalla que muestra el estilo estándar de Libros de Azure.

Formulario horizontal

En el formulario de estilo horizontal, los controles siempre son visibles, con la etiqueta en el lado izquierdo del control.

Captura de pantalla que muestra el estilo horizontal de formato de Libros de Azure.

Formulario vertical

En el formulario de estilo vertical, los controles siempre son visibles, con la etiqueta situada encima del control. A diferencia del estilo estándar, solo hay una etiqueta o control en una fila.

Captura de pantalla que muestra el estilo vertical de formato de Libros de Azure.

Nota

En los diseños estándar, formulario horizontal y formulario vertical, no hay ningún concepto de edición directa. Los controles siempre están en modo de edición.

Parámetros globales

Ahora que ha aprendido cómo funcionan los parámetros y las limitaciones sobre solo poder usar un parámetro "descendente" de donde se establece, es el momento de obtener información sobre los parámetros globales, que cambian esas reglas.

Con un parámetro global, el parámetro debe seguir declarándose antes de poder utilizarse. Pero cualquier paso que establezca un valor en ese parámetro afectará a todas las instancias de ese parámetro en el libro.

Nota

Dado que el cambio de un parámetro global tiene este comportamiento de "actualizar todo", la configuración global solo debe activarse para los parámetros que requieren este comportamiento. Una combinación de parámetros globales que dependen entre sí puede crear un ciclo u oscilación en el que los globales competidores cambian entre sí. Para evitar ciclos, no se puede "volver a declarar" un parámetro declarado como global. Las declaraciones posteriores de un parámetro con el mismo nombre crearán un parámetro de solo lectura que no se pueda editar en ese lugar.

Usos comunes de los parámetros globales:

  1. Sincronización de intervalos de tiempo entre muchos gráficos:

    • Sin un parámetro global, cualquier pincel de intervalo de tiempo en un gráfico solo se exportará después de ese gráfico. Por lo tanto, al seleccionar un intervalo de tiempo en el tercer gráfico, solo se actualizará el cuarto gráfico.
    • Con un parámetro global, puede crear un parámetro timeRange global, darle un valor predeterminado y hacer que todos los demás gráficos lo usen como su intervalo de tiempo limitado y como su salida de pincel de tiempo. Además, establecer el valor Exportar solo el parámetro cuando se limpie un intervalo. Cualquier cambio del intervalo de tiempo en cualquier gráfico actualiza el parámetro timeRange global en la parte superior del libro. Esta funcionalidad se puede usar para que un libro actúe como un panel.
  2. Permiso para el cambio de la pestaña seleccionada en un paso de vínculos a través de vínculos o botones:

    • Sin un parámetro global, el paso de vínculos solo genera un parámetro para la pestaña seleccionada.
    • Con un parámetro global, puede crear un parámetro selectedTab global. A continuación, puede utilizar ese nombre de parámetro en las selecciones de pestañas en el paso de los vínculos. Puede pasar ese valor de parámetro al libro desde un vínculo, o bien mediante otro botón o vínculo para cambiar la pestaña seleccionada. El uso de botones de un paso de vínculos de esta manera puede hacer una experiencia similar a un asistente, donde los botones de la parte inferior de un paso pueden afectar a las secciones visibles encima de este.

Creación de un parámetro global

Al crear el parámetro en un paso de parámetros, use la opción Tratar este parámetro como una opción global en Configuración avanzada. La única manera de hacer un parámetro global es declararlo con un paso de parámetros. Los demás métodos para la creación de parámetros (a través de selecciones, limpiezas, vínculos, botones y pestañas) solo pueden actualizar un parámetro global. No pueden declararse a sí mismos.

Captura de pantalla que muestra la configuración de los parámetros globales en un libro.

El parámetro estará disponible y funcionará como lo hacen los parámetros normales.

Actualización del valor de un parámetro global existente

Para el ejemplo de gráfico anterior, la forma más común de actualizar un parámetro global es mediante el barrido de tiempo.

En este ejemplo, el parámetro timerange se declara como global. En un paso de consulta inferior a ese, cree y ejecute una consulta que use ese parámetro timerange en la consulta y devuelva un resultado del gráfico de tiempo. En Configuración avanzada para el paso de consulta, habilite la configuración de barrido del intervalo de tiempo. Use el mismo nombre de parámetro que la salida del parámetro de pincel de tiempo. Además, establezca la opción Exportar solo el parámetro cuando se limpie un intervalo.

Captura de pantalla que muestra la configuración global del pincel de tiempo en un libro

Cada vez que se limpia un intervalo de tiempo en este gráfico, también actualiza el parámetro timerange anterior a esta consulta y el propio paso de consulta, ya que también depende de timerange.

  1. Antes de la limpieza:

    • El intervalo de tiempo se muestra como Última hora.
    • El gráfico muestra la última hora de los datos.

    Captura de pantalla de la configuración de los parámetros globales antes de la limpieza.

  2. Durante la limpieza:

    • El intervalo de tiempo sigue siendo la última hora y se dibujan los contornos de la limpieza.
    • No han cambiado parámetros. Una vez que suelte el pincel, se actualizará el intervalo de tiempo.

    Captura de pantalla de la configuración de los parámetros globales durante la limpieza.

  3. Después de la limpieza:

    • El intervalo de tiempo especificado por el pincel de tiempo se establece en este paso. Invalida el valor global. La lista desplegable timerange muestra ahora ese intervalo de tiempo personalizado.
    • Dado que el valor global de la parte superior ha cambiado y, dado que este gráfico depende de timerange como entrada, el intervalo de tiempo de la consulta que se usa en el gráfico también se actualiza. Como resultado, la consulta y el gráfico se actualizarán.
    • Cualquier otro paso del libro que dependa de timerange también se actualizará.

    Captura de pantalla de la configuración de los parámetros globales después de la limpieza.

    Nota

    Si no usa un parámetro global, el valor del parámetro timerange solo cambiará bajo este paso de consulta. Lo anterior a este paso o este elemento en sí no se actualizarán.