Parámetros de URL

Es posible mejorar un cuadro de mando con el uso eficaz de parámetros de URL. Un parámetro de URL es una propiedad que agrega un creador a la configuración de un cuadro de mando y que se puede usar para desencadenar acciones de . Con ello, los parámetros de URL permiten que el cuadro de mando se pueda mostrar de una forma determinada. Los parámetros de URL también resultan útiles cuando se integra un cuadro de mando en otra aplicación. En este escenario, puede utilizar la aplicación de alojamiento para cambiar la vista actual del cuadro de mando.

Nota:

Con la excepción del parámetro regional integrado, modificar los parámetros de un cuadro de mando durante el tiempo de ejecución no hará que se vuelva a cargar en la mayoría de navegadores modernos.

Un parámetro de URL es un par nombre-valor. En cada parámetro, el nombre y el valor se separan por el signo igual (=). Durante el tiempo de ejecución, puede agregar un parámetro al final de la URL del cuadro de mando con un signo de interrogación (?) seguido del parámetro.

Por ejemplo, una URL de cuadro de mando con un parámetro podría ser <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value.

En el caso de varios parámetros, agregue el símbolo et (&) entre cada uno: <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value&param2=value2

Sugerencia:

El orden de los parámetros es irrelevante. Por ejemplo, param=value&param2=value2 y param2=value2&param=value tienen el mismo resultado.

Los nombres de los parámetros están compuestos de caracteres alfanuméricos ASCII. También se permiten el guion (-) y el guion bajo ( _ ) en cualquier posición que no sea la primera. Los caracteres no válidos se bloquean en el momento del diseño con una advertencia de validación. La mejor práctica es evitar el uso de nombres largos de parámetros.

Nota:

Algunos nombres de parámetros se han reservado para el uso interno, como mode y edit. Al crear un parámetro, se produce la advertencia de validación Ya utilizado si usa un nombre que esté reservado.

Precaución:

Tanto los parámetros de la URL como los selectores se usan para proporcionar interacciones entre los elementos del cuadro de mando. Sin embargo, cuando se usan para abordar los mismos elementos, pueden contradecirse unos a otros y provocar resultados inesperados. Tenga cuidado al diseñar las interacciones de su cuadro de mando.

Codificación de la URL

Al transmitir un parámetro a un cuadro de mando durante el tiempo de ejecución, codifique su valor. La codificación garantiza que los caracteres no válidos se sustituyan por %, seguidos de su equivalente hexadecimal.

A continuación, por ejemplo, se transmite el valor Main Street por un parámetro de URL:

<scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=Main%20Street

Al transmitir un parámetro de URL como lista de valores separados por comas, tenga en cuenta lo siguiente:

• Codifique cada valor por separado.

  Correcto

  ?param=Main%20Street,Broadway%20Avenue

  Incorrecto. No codifique la coma que se usa para separar los valores.

  ?param=Main%20Street%2CBroadway%20Avenue

• No incluya espacios entre los valores.

  Correcto

  ?param=Main%20Street,Broadway%20Avenue

  Incorrecto

  ?param=Main%20Street, Broadway%20Avenue

Tipos de parámetros de URL

Existen cinco tipos de parámetros de URL: categoría, numérico, fecha, entidad y geometría. Para obtener información sobre los tipos de acciones que se pueden desencadenar con los distintos tipos de parámetros, consulte Configurar acciones en parámetros de URL.

Parámetro de categoría

Puede utilizar un parámetro de categoría para aplicar una acción de filtrado a uno o varios elementos. En el momento del diseño, especifique el nombre del parámetro, si las entradas serán de tipo cadena de caracteres o numéricas y si las consultas de filtro incluirán o no los valores transmitidos.

Durante el tiempo de ejecución, los parámetros de categoría aceptan un valor único o varios valores separados una coma. No incluya ningún espacio después de la coma.

Cuando se transmite un valor único, la consulta interna usa el operador comparativo igual que o no igual que para filtrar los elementos de destino. Cuando se transmiten varios valores, se usan los operadores lógicos IN o NOT IN.

Ejemplos

En la siguiente tabla, unas notas indican si el parámetro de categoría se ha configurado para esperar una cadena de caracteres o un número:

Parámetro	Nota
?status=DAMAGED	Cadena
?status=DAMAGED,DESTROYED	Cadena de caracteres con varios valores
?category=1	Número
?category=1,2	Número con varios valores

Ejemplos de casos especiales

Las categorías de datos no siempre están especificadas, en el caso de las cadenas de caracteres, es posible que estén vacías. Por lo tanto, los parámetros de categoría admiten los siguientes cuatro casos especiales:

• ((null))
• ((notnull))
• ((empty))
• ((notempty))

Parámetro	Nota
?status=((null))	Filtro para los valores que son NULL.
?status=((notnull)	Filtro para los valores que son NOT NULL.
?status=((empty))	Filtro para los valores que están vacíos.
?status=((notempty))	Filtro para los valores que no están vacíos.
?status=DAMAGED,((null))	Filtro para el valor transmitido O que es NULL.
?status=DAMAGED,DESTROYED,((null))	Filtro para varios valores transmitidos O que son NULL.

Parámetros numéricos

Puede utilizar parámetros numéricos para aplicar una acción de filtrado a uno o varios elementos de destino. En el momento del diseño, especifique el nombre del parámetro y si los valores de entrada esperados serán un valor único o dos valores que representen un rango. Cuando se usa un valor único, el parámetro se configura para aplicar uno de los siguientes operadores de comparación:

• igual
• no igual
• es menor que
• es menor o igual que
• es mayor que
• es mayor o igual que

Sugerencia:

Para obtener mayor control que el que ofrece el tipo de valor de rango, cree dos parámetros numéricos únicos y aplique la condición de filtro (operador) que cumpla sus requisitos. Durante el tiempo de ejecución, los parámetros únicos se combinan con un operador lógico AND al aplicar un filtro a los elementos de destino.

Durante el tiempo de ejecución, los parámetros numéricos se transmiten como un valor único o dos valores separados por una coma.

Ejemplos

En la siguiente tabla, unas notas indican si el parámetro numérico se ha configurado para esperar un valor único o un rango:

Parámetro	Nota
?meas=10	Valor único
?meas=10,15	Intervalo

Ejemplos de casos especiales

Los valores numéricos de los datos no siempre se especifican. Por lo tanto, los parámetros numéricos admiten dos casos especiales: ((null)) y ((notnull)). Puede utilizar estas etiquetas de casos especiales en flujos de trabajo tanto de valor único como de rango numérico.

Parámetro	Nota
?meas=((null))	Rango numérico o valor de fecha único. Filtro para los valores que son NULL.
?meas=((notnull))	Rango numérico o valor de fecha único. Filtro para los valores que son NOT NULL.
?meas=10,((null))	Valor único. Filtro para el valor O los valores que son NULL.
?meas=10,15,((null))	Rango numérico. Filtro para los números del rango O para los valores que son NULL.

Otro caso especial es cuando un parámetro numérico espera un rango, pero solo se proporciona un valor único durante el tiempo de ejecución.

Parámetro	Nota
?meas=,10	Izquierdo abierto. Se filtran los valores menores o iguales que este valor.
?meas=10,	Derecho abierto. Se filtran los valores mayores o iguales que este valor.
?meas=10	Derecho abierto. Se filtran los valores mayores o iguales que este valor.
?meas=10,((null))	Derecho abierto. Filtrar valores mayores o iguales que este valor O que son NULL.

Parámetros de fecha

Puede utilizar parámetros de fecha para aplicar una acción de filtrado a uno o varios elementos de destino. En el momento del diseño, especifique el nombre del parámetro y si los valores de entrada esperados serán cadenas de caracteres de fecha ISO 8601 o de Época de UNIX.

Puede configurar parámetros de fecha para procesar un valor único o dos valores que representen un rango de fechas. Cuando se usa un valor único, el parámetro se configura para aplicar uno de los siguientes operadores de comparación:

• es
• no es
• es anterior a
• es o es anterior a
• es posterior a
• es o es posterior a

Sugerencia:

Para obtener mayor control que el que ofrece el tipo de valor de rango, cree dos parámetros de fecha únicos y aplique la condición de filtro (operador) que cumpla sus requisitos. Durante el tiempo de ejecución, los parámetros únicos de fecha se combinan con un operador lógico AND al aplicar un filtro a los elementos de destino.

Durante el tiempo de ejecución, los parámetros de fecha se transmiten como un valor único o dos valores separados por una coma. Si un parámetro de fecha es de Época de UNIX, debe ser un entero de 32 bits con signo. Si es una cadena de caracteres, las fechas deben tener el formato AAAA-MM-DD o AAAAMMDD. Las fechas se introducen según el calendario gregoriano y están compuestas de años, meses y días.

• AAAA: Año de cuatro dígitos (AAAA)
• MM: mes de dos dígitos del año (01 hasta 12)
• DD: día de dos dígitos (01 hasta 31)

Sugerencia:

La lista de formatos de fecha admitidos por los parámetros de fecha es distinta de los admitidos por el gráfico de serie de fechas de análisis.

También se puede incluir la parte de hora con la fecha. Las horas se introducen con formato de 24 horas y están compuestas de horas, minutos y segundos. Puede formatearlas como hh:mm:ss o hhmmss. Si no se contiene ninguna parte de hora con la fecha, significa que se contiene todo el día desde las 00:00:00 hasta las 23:59:59.

• hh: hora con relleno de ceros entre 00 y 24
• mm: minuto con relleno de ceros entre 00 y 59
• ss: segundo con relleno de ceros entre 00 y 59

Si se especifica, la parte de hora se separa de la parte de fecha con un espacio o una T en mayúsculas. A continuación, se muestran fechas válidas transmitidas como cadenas de caracteres:

Fecha	Nota
2018-10-31	Solo fecha
20181031	Solo fecha (formato alternativo)
2018-10-31T23:14:42	Fecha y hora separadas por T
20181031T231442	Fecha y hora separadas por T (formato alternativo)
31/10/2018 23:14:42	Fecha y hora separadas por un espacio
20181031 231442	Fecha y hora separadas por un espacio (formato alternativo)

Sugerencia:

Se recomienda separar la fecha y la hora con una T en mayúsculas. Si usa un espacio, codifíquelo.

Cuando se transmiten las fechas a un cuadro de mando durante el tiempo de ejecución, se presupone que su componente de hora se especifica en la zona horaria local. Es decir, la zona horaria del equipo o dispositivo en el que se ejecuta el navegador. Para obtener control adicional, también puede especificar la hora como hora universal coordinada (UTC) o como desplazamiento respecto de la UTC. Para indicar que la hora está en UTC, agregue la letra Z justo después de la hora, sin espacios. La Z es el designador de zona cuando no hay desplazamiento respecto de la UTC. Se incorpora un desplazamiento respecto de la UTC a la hora en formato ±hh:mm, ±hhmm, o ±hh.

Fecha	Nota
2018-10-31T23:14:42Z	UTC
2018-10-31T23:14:42+01:00	Una hora más que UTC
2018-10-31T23:14:42+0100	Una hora más que UTC
2018-10-31T23:14:42+01	Una hora más que UTC
2018-10-31T23:14:42-05:00	Cinco horas menos que UTC
2018-10-31T23:14:42-0500	Cinco horas menos que UTC
2018-10-31T23:14:42-05	Cinco horas menos que UTC

Al crear filtros a partir de parámetros de fecha, los cuadros de mando examinan la fuente de datos del elemento de destino para ver la información de la zona horaria. Si se encuentra, las consultas se envían en esa zona horaria. Si no se encuentra la zona horaria, se presupone que la fuente de datos de destino es UTC. En cualquier caso, es posible que el cuadro de mando tenga que convertir las horas de entrada para que coincidan con las de destino.

Sugerencia:

Si un cuadro de mando recibe un parámetro de fecha con un formato que no reconoce, se ignora durante el tiempo de ejecución.

Ejemplos

En la siguiente tabla, unas notas indican si el parámetro de fecha se ha configurado para esperar una sola fecha o un rango de fechas. Se ofrecen ejemplos de Época de UNIX y cadena de caracteres de fecha.

Parámetro	Nota
?created=1541027682	Valor único que utiliza Época de UNIX.
?created=2018-10-31	Valor único que utiliza una cadena de caracteres de fecha, con el día completo implícito.
?created=2018-10-31T23:14:42	Valor único que utiliza una cadena de caracteres de fecha, con la hora. El uso de la zona horaria local es implícito.
?created=2018-10-31T23:14:42Z	Valor único que utiliza una cadena de caracteres de fecha, con la hora en UTC.

Ejemplos de casos especiales

Los valores de fecha no siempre están definidos. Por lo tanto, los parámetros de fecha admiten dos casos especiales: ((null)) y ((notnull)). Estas etiquetas de casos especiales se pueden usar en flujos de trabajo tanto de valor único como de rango de fecha.

Parámetro	Nota
?created=((null))	Rango de fechas o valor de fecha único. Filtro para las fechas NULL.
?created=((notnull))	Rango de fechas o valor de fecha único. Filtro para las fechas que son NOT NULL.
?created=2018-10-31,((null))	Valor de fecha único. Filtro para el 31 de octubre O las fechas que son NULL.
?created=2018-10-31,2018-11-05,((null))	Rango de fechas. Filtrar las fechas del rango O las fechas que son NULL.

Otro caso especial es cuando un parámetro de fecha espera un rango, pero solo se proporciona un valor único durante el tiempo de ejecución.

Parámetro	Nota
?created=,2018-10-31	Izquierdo abierto. Se filtrarán las fechas de ese día o anteriores.
?created=2018-10-31,	Derecho abierto. Se filtrarán las fechas de ese día o posteriores.
?created=2018-10-31,((null))	Derecho abierto. Filtrar las fechas de ese día o anteriores O las fechas que son NULL.

Parámetros de entidad

Los parámetros de entidad se usan para transmitir uno o varios Id. de entidades a un cuadro de mando. Se pueden usar para filtrar los elementos del cuadro de mando o para aplicar acciones de ubicación (Zoom, Desplazamiento panorámico, Mostrar ventana emergente, Seguir entidad y Destacar) a los mapas del cuadro de mando.

En el momento del diseño, especifique el nombre del parámetro y seleccione una fuente de datos. El campo de Id. único de la fuente de datos debe estar identificado. Si no se selecciona correctamente un campo que contenga valores no únicos, se produce un comportamiento inesperado durante el tiempo de ejecución.

Sugerencia:

Si la fuente de datos seleccionada contiene polígonos, se puede usar para aplicar filtros espaciales a los elementos de destino.

Durante el tiempo de ejecución, asegúrese de codificar con URL los Id. de entidades si los valores de la capa de destino son cadenas de caracteres. Es posible transmitir varios Id. de entidades separándolos con comas, por ejemplo, ?asset=1240,1241,1242. No incluya ningún espacio después de cada coma.

Sugerencia:

Si se configura un parámetro de entidad para que realice una acción de Seguir entidad, solo se espera un Id. Si se transmiten varios valores, solo se sigue una de las entidades. La que se sigue no refleja necesariamente el orden de los Id. que se transmiten.

Ejemplos

Parámetro	Nota
?id=11033	Valor único
?id=11033,23034,34035	Varios valores

Parámetros de geometría

Existen dos tipos de parámetros de geometría: punto y extensión. Si el tipo es de punto, los parámetros de geometría se usan para acercarse, desplazarse o destacar una ubicación en uno o varios mapas del cuadro de mando. Si el tipo es de extensión, puede utilizar los parámetros de geometría para definir las extensiones de mapa del cuadro de mando o filtrar sus otros elementos. En el momento del diseño, especifique el nombre del parámetro y seleccione el tipo de geometría antes de configurar las acciones.

Durante el tiempo de ejecución, todas las coordenadas de la geometría se transmiten como valores del Sistema geodésico mundial de 1984 (WGS84) separados por comas. En el caso de parámetros de punto, el formato es x,y. En el caso de parámetros de extensión, el formato es leftX,leftY,rightX,rightY. En cualquier caso, no hay espacios después de la coma.

Ejemplos

Parámetro	Nota
?pt=-75.6971931,45.4215296	El parámetro de geometría espera un punto
?ext=-80.6,40.6,-70.7,47.7	El parámetro de geometría espera una extensión

Cambiar la configuración regional

Los cuadros de mando presentan un parámetro de URL integrado, el código de configuración regional (o "locale" en inglés), para cambiar el idioma y los formatos de número y fecha utilizados al mostrar contenido. Agregue el parámetro ?locale=<language code> al final de la URL del cuadro de mando. El parámetro integrado se puede usar junto con cualquier parámetro de URL configurado por un creador separando varios parámetros de URL con un símbolo et (&).

En la tabla que aparece a continuación se enumeran los códigos de idioma admitidos:

Código de idioma	Idioma
ar	Árabe
bs	Bosnio
ca	Catalán
cs	Checo
da	Danés
de	Alemán
el	Griego
en	Inglés
es	Español
et	Estonio
fi	Finlandés
fr	Francés
he	Hebreo
hr	Croata
hu	Húngaro
id	Indonesio
it	Italiano
ja	Japonés
ko	Coreano
lt	Lituano
lv	Letón
nb	Noruego Bokmål
nl	Neerlandés
pl	Polaco
pt-br	Portugués (Brasil)
pt-pt	Portugués (Portugal)
ro	Rumano
ru	Ruso
sl	Esloveno
sr	Serbio
sv	Sueco
th	Tailandés
tr	Turco
uk	Ucraniano
vi	Vietnamita
zh-cn	Chino (simplificado)
zh-hk	Chino (tradicional de Hong Kong)
zh-tw	Chino (tradicional de Taiwán)

Al utilizar códigos de idioma de inglés, español, francés, alemán e italiano, también puede utilizar los siguientes códigos de configuración regional para establecer el formato de los números y fechas:

Código de configuración regional	Formato de número y fecha
en-au	Inglés (Australia)
en-ca	Inglés (Canadá)
en-gb	Inglés (Gran Bretaña)
es-es	Español (España)
es-mx	Español (México)
fr-ch	Francés (Suiza)
de-ch	Alemán (Suiza)
it-ch	Italiano (Suiza)

La siguiente URL es un ejemplo de la especificación de la configuración regional francesa:

https://<yourPortalUrl>/apps/opsdashboard/index.html#/4f539791b2f1418cb5403891f1a7be50?locale=fr