Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En Operaciones de IoT de Azure, una transformación de mapa toma cada mensaje entrante en un grafo de flujo de datos y produce un mensaje de salida basado en tus reglas. Puede cambiar el nombre de los campos, reorganizarlos en nuevas estructuras, calcular valores derivados o eliminar los campos no deseados. Usando reglas comodines, puedes copiar todos los campos a la vez.
Para obtener información general sobre los gráficos de flujo de datos y cómo las transformaciones se componen en una canalización, consulte Introducción a los gráficos de flujo de datos.
Las transformadas utilizan un lenguaje de expresiones para calcular valores, condiciones de prueba y campos de referencia. Las expresiones se refieren a las entradas por posición, no por nombre: la primera entrada en la inputs lista es $1, la segunda es $2, y así sucesivamente. Las funciones integradas, como cToF, convierten y manipulan esos valores.
Para la lista completa de operadores, funciones, tipos de datos y campos de metadatos, consulte la referencia Expressions.
Prerrequisitos
- Instancia de Operaciones de IoT de Azure implementada en un clúster de Kubernetes. Para obtener más información, consulte Deploy Operaciones de IoT de Azure.
- Un punto de conexión del Registro predeterminado denominado
defaultque apunta amcr.microsoft.comse crea automáticamente durante la implementación. Las transformaciones integradas usan este endpoint.
Los CLI de Azure ejemplos de este artículo usan variables de entorno para que puedas establecer cada valor una vez y luego copiar y pegar los comandos as-is. Si usas el entorno Operaciones de IoT de Azure Codespaces del quickstart, estas variables ya están configuradas para ti y puedes saltarte este paso. De lo contrario, configura las siguientes variables de entorno en tu shell antes de ejecutar los comandos.
Los siguientes scripts establecen las variables de entorno más usadas:
| Variable del entorno | Descripción |
|---|---|
SUBSCRIPTION_ID |
El ID de la suscripción que contiene tu instancia de Operaciones de IoT de Azure. |
RESOURCE_GROUP |
El nombre del grupo de recursos que contiene tu instancia de Operaciones de IoT de Azure. |
AIO_INSTANCE_NAME |
El nombre de tu instancia de Operaciones de IoT de Azure. Para listar tus instancias, ejecuta az iot ops list -o table. |
CLUSTER_NAME |
El nombre del clúster Kubernetes habilitado para Azure Arc que aloja tu instancia. |
LOCATION |
La región de Azure para usar para nuevos recursos, por ejemplo eastus. |
SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>
Solo necesitas establecer las variables que utiliza este artículo. Este artículo podría utilizar variables de entorno adicionales para los nombres de recursos que elijas. El artículo explica cómo situarlos donde se introducen.
Funcionamiento de las reglas del mapa
Cada regla de mapa tiene cuatro partes:
| Propiedad | Obligatorio | Descripción |
|---|---|---|
inputs |
Sí | Lista de rutas de campo para leer del mensaje entrante. |
output |
Sí | Ruta de campo donde aparece el resultado en el mensaje de salida. |
expression |
No | Fórmula aplicada a los valores de entrada. Si lo omites, el primer valor de entrada se copia directamente. |
description |
No | Etiqueta legible para el usuario correspondiente a la regla, que se incluye en los mensajes de error. |
La transformada de mapa asigna variables posicionales a las entradas en orden. Por ejemplo, si inputs es , entonces ['Position', 'Office'] es el valor de $1 y Position es el valor de $2Office.
Cambiar el nombre de un campo
Para cambiar el nombre BirthDate a DateOfBirth, asigne una entrada a otra ruta de acceso de salida. No necesitas una expresión. El valor se copia tal cual.
En la configuración de transformación de mapa, agregue una regla:
| Configuración | Importancia |
|---|---|
| Input | BirthDate |
| Salida | DateOfBirth |
Reestructurar campos
Utiliza la notación de puntos en la ruta de salida para mover campos a una estructura anidada.
Agregue dos reglas:
| Entrada | Salida |
|---|---|
Name |
Employee.Name |
BirthDate |
Employee.DateOfBirth |
Dada esta entrada:
{
"Name": "Grace Owens",
"BirthDate": "19840202",
"Position": "Analyst"
}
Estas dos reglas producen:
{
"Employee": {
"Name": "Grace Owens",
"DateOfBirth": "19840202"
}
}
Solo los campos enumerados en la salida de una regla aparecen en el resultado. El resultado no incluye el Position campo porque ninguna regla lo mapea.
Combinar varias entradas
Cuando listes múltiples entradas, usa sus variables posicionales para fusionarlas en una expresión.
Agregue una regla:
| Configuración | Importancia |
|---|---|
| Entradas |
Position, Office |
| Salida | Employment.Position |
| Expresión | $1 + ", " + $2 |
Dada Position: "Analyst" y Office: "Kent, WA", la salida es "Analyst, Kent, WA".
Transformación de valores con expresiones
Use el expression campo para aplicar funciones integradas o aritméticas. El siguiente ejemplo utiliza cToF, una función de conversión unitaria incorporada que convierte un valor Celsius en Fahrenheit. Recuerda que eso $1 se refiere a la primera entrada, no a un nombre de campo.
Para la lista completa de operadores, funciones y características avanzadas, véase la referencia Expressions. La referencia agrupa funciones por categoría, como conversión de unidades, escalado y redondeo, matemáticas y funciones de cadena .
Agregue una regla de cálculo. Por ejemplo, para convertir Celsius a Fahrenheit:
| Configuración | Importancia |
|---|---|
| Input | temperature |
| Salida | temperature_f |
| Expresión | cToF($1) |
Para escalar una lectura de sensor a un intervalo de 0 a 100, use la expresión scale($1, 0, 4095, 0, 100).
Copiar todos los campos con caracteres comodín
Cuando la salida debe coincidir estrechamente con la entrada con solo unos pocos cambios, use una regla comodín para copiar cada campo a la vez. A continuación, agregue reglas para invalidar, agregar o quitar campos específicos.
Agregue una regla de acceso directo que copie todos los campos. Establezca la entrada en * y la salida en *.
Requisitos para las reglas de caracteres comodín
- Una regla de caracteres comodín debe ser la primera regla de la configuración del mapa.
- Una transformación de mapa solo soporta una regla comodín.
- El asterisco coincide con uno o varios segmentos de ruta de acceso y debe representar un segmento completo. La transformación de mapa no soporta patrones parciales como
partial*.
Caracteres comodín de prefijos
Ajusta el comodín a un prefijo específico. Para aplanar todos los campos desde ColorProperties hasta el nivel raíz.
Agregue una regla con entrada ColorProperties.* y salida *.
Con estas premisas:
{
"ColorProperties": {
"Hue": "blue",
"Saturation": "90%",
"Brightness": "50%"
}
}
La salida es la siguiente:
{
"Hue": "blue",
"Saturation": "90%",
"Brightness": "50%"
}
Quitar campos de la salida
Establezca en output una cadena vacía para excluir campos específicos. Normalmente, usa este enfoque tras una regla de comodín: copia todo y luego elimina lo que no necesites.
- Agregue una regla de acceso directo para copiar todos los campos.
- Agregue una regla de eliminación y seleccione los campos que se van a excluir (por ejemplo,
passwordyinternal_id).
Una regla de eliminación no puede incluir una expresión.
Invalidar caracteres comodín en campos específicos
Cuando una regla comodín y una regla específica coinciden con el mismo campo, la regla más específica tiene prioridad.
- Agregue una regla de acceso directo para copiar todos los campos.
- Agregue una regla de proceso para
temperaturecon la expresióncToF($1).
La transformación de mapa aplica la regla específica a temperature y copia todos los demás campos as-is.
Uso de campos de metadatos
Lee y escribe en metadatos de mensajes como temas MQTT y propiedades de usuario. Consulte Campos de metadatos en la referencia de expresiones.
Agregue una regla con entrada region y salida $metadata.user_property.region para escribir un valor de campo en una propiedad de usuario MQTT.
Para obtener un ejemplo completo del enrutamiento dinámico de temas, consulte Enrutamiento de mensajes a distintos temas.
Usar el último valor conocido y los valores por defecto
Cuando los datos del sensor llegan de forma intermitente, puede rellenar los campos que faltan con el último valor conocido o un valor predeterminado estático. Consulte Último valor conocido y Valores predeterminados en la referencia de expresiones.
Agregue una regla para el temperature campo y habilite Último valor conocido. Establezca un valor predeterminado de 0 como reserva.
Esta regla usa el valor actual cuando está presente, vuelve al último valor conocido y usa 0 si ninguno está disponible.
Enriquecimiento con datos externos
El enriquecimiento es opcional. Solo lo necesitas si quieres combinar los mensajes entrantes con datos de referencia almacenados en el almacén de estados, como una tabla de consulta con metadatos de dispositivos. Si tus mensajes ya contienen todo lo que necesitas, salta esta sección.
Cuando necesites enriquecimiento, configura un conjunto de datos de contextualización que el runtime consulte durante el procesamiento. Por ejemplo, busque los metadatos de un dispositivo por su identificador e inclúyelo en la salida. Para más información, consulte Enriquecimiento con datos externos.
Características exclusivas del grafo de flujo de datos
Los gráficos de flujo de datos admiten varias funcionalidades que no están disponibles en las asignaciones de flujo de datos de builtInTransformation.
Valores predeterminados para los campos que faltan
Use la sintaxis ?? <default> en una entrada para proporcionar una alternativa estática cuando falta un campo. Esto es más sencillo que escribir una if expresión para comprobar si hay valores vacíos.
En la configuración de transformación de la asignación, cambie la entrada para que incluya la sintaxis ?? seguida del valor predeterminado. Por ejemplo, introduzca temperature ?? 0 como el campo de entrada que se utilizará cuando falte el campo de temperatura 0.
Para más información sobre los tipos predeterminados admitidos y la combinación de valores predeterminados con los últimos valores conocidos, consulte Valores predeterminados en la referencia de expresiones.
Funciones de Regex (expresiones regulares)
Los gráficos de flujo de datos admiten la coincidencia y sustitución de expresiones regulares:
-
str::regex_matches(string, pattern): devuelve true si la cadena coincide con el patrón regex. -
str::regex_replace(string, pattern, replacement): reemplaza todas los resultados positivos de expresiones regulares por la cadena de reemplazo.
Estas funciones son útiles en expresiones de filtro o para limpiar y transformar datos de cadena. Para obtener la lista completa de funciones de cadena, vea Funciones de cadena en la referencia de expresiones.
Ejemplo de configuración completa
Esta es una configuración de mapa completa que copia todos los campos, quita datos confidenciales, reestructura un campo y calcula un valor derivado:
En la experiencia de Operaciones, cree un diagrama de flujo de datos y agregue una transformación de mapa. En el panel de configuración del mapa, agregue reglas a:
- Copie todos los campos con un paso directo mediante caracteres comodín.
-
Quite los campos confidenciales estableciendo la salida en vacía para
passwordysecret_key. -
Reestructurar el
BirthDatecampo aEmployee.DateOfBirth. -
Calcula una conversión Fahrenheit usando la fórmula
cToF($1)en eltemperaturecampo. -
Combine los
Positioncampos yOfficecon la fórmula$1 + ", " + $2.