O que é jq em pipelines de processador de dados?

Importante

O recurso Pré-visualização de Operações do Azure IoT — habilitado pelo Azure Arc — está atualmente em VERSÃO PRÉVIA. Você não deve usar esse software em versão prévia em ambientes de produção.

Você precisará implantar uma nova instalação do Azure IoT Operations quando uma versão geralmente disponível for disponibilizada, você não poderá atualizar uma instalação de visualização.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

jq é um processador JSON de código aberto que você pode usar para reestruturar e formatar cargas estruturadas no processador de dados):

• O filtro do estágio de pipeline usa o jq para habilitar consultas de filtro flexíveis.
• A estágio de pipeline da transformação usa o jq para habilitar a transformação de dados.

Dica

O jq não é o mesmo que o jQuery e resolve um conjunto diferente de problemas. Quando você pesquisa online informações sobre o jq, os resultados da pesquisa podem incluir informações o jQuery. Certifique-se de ignorar ou excluir as informações do jQuery.

O jq que você fornece nestes estágios deve ser:

• Sintaticamente válido.
• Semanticamente válido para a mensagem à qual o jq é aplicado.

Como usar o jq

Há duas maneiras de usar a linguagem jq nos estágios do pipeline do processador de dados:

• Expressões que usam todo o poder da linguagem do jq, incluindo a capacidade de executar manipulações e cálculos arbitrários com seus dados. As expressões aparecem em estágios de pipeline, como filtro e transformação, e são chamadas de expressões onde são usadas.
• Os caminhos identificam um único local em uma mensagem. Os caminhos usam um pequeno subconjunto da linguagem jq. Você usa caminhos para recuperar informações de mensagens e colocar informações computadas de volta na mensagem para processamento posterior em um pipeline.

Dica

Este guia não fornece uma visão completa dos recursos do jq. Para obter a referência completa da linguagem, confira o manual do jq.

Por motivos de desempenho, o processador de dados bloqueia o uso das seguintes funções jq:

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

Solução de problemas

À medida que você cria caminhos ou expressões do jq no processador de dados, há algumas coisas a serem lembradas. Se você estiver enfrentando problemas, certifique-se de não cometer um dos seguintes erros:

Sem escopo para payload

Todas as mensagens nos pipelines do processador de dados começam com uma estrutura que coloca o conteúdo da mensagem em um campo de nível superior chamado payload. Embora não seja obrigatório, é forte recomendado quando você processa mensagens manter o conteúdo principal dentro do campo payload à medida que a mensagem passa pelos vários estágios do pipeline.

A maioria dos casos de uso para transformação e filtragem envolve trabalhar diretamente com o conteúdo, portanto, é comum ver toda a consulta com escopo no campo de conteúdo. Você pode esquecer que as mensagens usam essa estrutura e tratam o conteúdo como se estivesse no nível superior.

A correção desse erro é simples. Se você estiver usando o jq para:

• Filtrar mensagens, adicione o .payload | ao início de sua expressão para definir o escopo corretamente.
• Transformar mensagens:
  • Se você não estiver dividindo a mensagem, adicione .payload |= ao início da expressão para definir o escopo da sua transformação.
  • Se você estiver dividindo a mensagem, adicione .payload = (.payload | <expression>) em seu <expression> para atualizar o conteúdo especificamente, permitindo que a mensagem seja dividida.

Tentando combinar várias mensagens

O jq tem muitos recursos que permitem separar mensagens e reestruturá-las. No entanto, apenas uma única mensagem de cada vez que entra em um estágio de pipeline pode invocar uma expressão do jq. Portanto, não é possível somente com filtros e transformações combinar dados de múltiplas mensagens de entrada.

Se desejar mesclar valores de diversas mensagens, use um estágio agregado para combinar os valores primeiro e, em seguida, use transformações ou filtros para operar nos dados combinados.

Separando argumentos de função com , em vez de ;

Ao contrário da maioria das linguagens de programação, o jq não usa o , para separar argumentos de funções. O jq separa cada argumento de função com o ;. Esse erro pode ser difícil de depurar porque , é uma sintaxe válida na maioria dos lugares, mas significa algo diferente. No jq, , separa os valores em um fluxo.

O erro mais comum que você vê ao usar um , em vez de um ; é uma reclamação de que a função que você está tentando invocar não existe para o número de argumentos fornecidos. Se você receber algum erro de compilação ou qualquer outro erro estranho ao chamar uma função que não faz sentido, certifique-se de usar o ; em vez de , para separar seus argumentos.

Ordem de operações

A ordem das operações no jq pode ser confusa e contraintuitiva. Normalmente, as operações entre caracteres | são executadas juntas antes que o jq aplique o |, mas há algumas exceções. Em geral, adicione o () em qualquer coisa onde você não tenha certeza da ordem natural das operações. À medida que você usa mais a linguagem, você aprende o que precisa de parênteses e o que não precisa.

Conteúdo relacionado

Consulte estes artigos para obter ajuda ao usar o jq:

• Caminhos jq
• Expressões jq