¿Qué es jq en una canalización de la versión preliminar del procesador de datos de Azure IoT?

Importante

Operaciones de IoT de Azure, habilitado por Azure Arc, está actualmente en VERSIÓN PRELIMINAR. No se debería usar este software en versión preliminar en entornos de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

jq es un procesador JSON de código abierto que puede usar cargas estructuradas de reestructuración y formato en canalizaciones de Procesador de datos de Azure IoT (versión preliminar):

• La fase de canalización de filtro usa jq para habilitar consultas de filtro flexibles.
• La fase de canalización de transformación usa jq para habilitar la transformación de datos.

Sugerencia

jq no es lo mismo que jQuery y resuelve un conjunto diferente de problemas. Al buscar información en línea sobre jq, los resultados de la búsqueda podrían incluir jQuery de información. Asegúrese de omitir o excluir la información de jQuery.

El jq que se proporcione en estas fases deberá ser:

• Sintácticamente válido.
• Semánticamente válido para el mensaje al que se aplique jq.

Cómo usar jq

Hay dos maneras de usar el lenguaje jq en las fases de canalización del procesador de datos:

• Expresiones que usan toda la eficacia del lenguaje jq, incluyendo la capacidad de desempeño de manipulaciones arbitrarias y cálculos con los datos. Las expresiones aparecen en las fases de canalización, como el filtro y la transformación, y se conocen como expresiones allá donde se usan.
• Rutas de acceso que identifican una sola ubicación en un mensaje. Las rutas de acceso usan un pequeño subconjunto del lenguaje jq. Las rutas de acceso se usan para recuperar información de los mensajes y para volver a colocar la información calculada en el mensaje para su procesamiento posterior en una canalización.

Sugerencia

Esta guía no proporciona una imagen completa de las características de jq. Para obtener la referencia completa del lenguaje, consulte el manual de jq.

Por motivos de rendimiento, el procesador de datos bloquea el uso de las siguientes funciones de jq:

• Modulemeta
• Range
• Recurse
• Until
• Walk
• While

Solución de problemas

A medida que compila rutas de acceso o expresiones de jq en el procesador de datos, hay algunas cosas que hay que tener en cuenta. Si tiene problemas, asegúrese de que no esté cometiendo uno de los siguientes errores:

No determinar el ámbito de payload

Todos los mensajes de las canalizaciones de procesador de datos comienzan con una estructura que coloca la carga del mensaje en un campo de nivel superior denominado payload. Aunque no es necesario, resulta una fuerte convención el procesar los mensajes para mantener la carga principal dentro del campo payload a medida que el mensaje pase por las distintas fases de canalización.

La mayoría de los casos de uso para la transformación y el filtrado implican trabajar directamente con la carga, por lo que es habitual ver toda la consulta en el ámbito del campo de carga. Podría olvidar que los mensajes usan esta estructura y tratar la carga como si estuviera en el nivel superior.

La corrección de este error es sencilla. Si usa jq para:

• Filtrar mensajes, agregue .payload | al inicio de la expresión para definir el ámbito correcto.
• Transformación de mensajes:
  • Si no divide el mensaje, agregue .payload |= al principio de la expresión para definir el ámbito de la transformación.
  • Si divide el mensaje, agregue .payload = (.payload | <expression>) alrededor de <expression> para actualizar la carga específicamente al permitir que el mensaje se divida.

Intentar combinar varios mensajes

jq tiene muchas características que permiten separar los mensajes y reestructurarlos. Sin embargo, solo un único mensaje a la vez que entre en una fase de canalización puede invocar una expresión jq. Por lo tanto, no es posible solo con filtros y transformaciones para combinar datos de varios mensajes de entrada.

Si desea combinar valores de varios mensajes, use una fase de agregado para combinar primero los valores y, a continuación, use transformaciones o filtros para operar sobre los datos combinados.

Separación de argumentos de función con , en lugar de ;

A diferencia de la mayoría de los lenguajes de programación, jq no usa , para separar argumentos de función. jq separa cada argumento de función con ;. Este error puede ser complicado de depurar porque , es una sintaxis válida en la mayoría de lugares, pero significa algo diferente. En jq, , separa los valores de una secuencia.

El error más común que se ve si se usa un , en lugar de un ; es una queja de que la función que intenta invocar no existe para el número de argumentos proporcionados. Si recibe algún error de compilación o cualquier otro error extraño al llamar a una función que no tenga sentido, asegúrese de usar ; en lugar de , para separar los argumentos.

Orden de las operaciones

El orden de las operaciones en jq puede ser confuso y contraintuitivo. Las operaciones entre | caracteres suelen ejecutarse juntas antes de que jq aplique el |, pero hay algunas excepciones. En general, agregue () alrededor de cualquier cosa donde no esté seguro del orden natural de las operaciones. A medida que use más el lenguaje, aprenderá qué necesita paréntesis y qué no.

Contenido relacionado

Consulte estos artículos para obtener ayuda al usar jq:

• Rutas de acceso de jq
• Expresiones de jq