Partilhar via

O que é jq em pipelines de processador de dados?

  • Artigo

Importante

Azure IoT Operations Preview – habilitado pelo Azure Arc está atualmente em visualização. Não deve utilizar este software de pré-visualização em ambientes de produção.

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

Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

jq é um processador JSON de código aberto que você pode usar para reestruturar e formatar cargas úteis estruturadas nos pipelines do processador de dados:

Gorjeta

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

O jq que você fornece nestas etapas 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 de pipeline do processador de dados:

  • Expressões que usam todo o poder da linguagem jq, incluindo a capacidade de realizar manipulações arbitrárias e cálculos com seus dados. As expressões aparecem em estágios de pipeline, como filtrar e transformar, 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 para colocar informações computadas de volta na mensagem para processamento posterior em um pipeline.

Gorjeta

Este guia não fornece uma imagem completa dos recursos do jq. Para obter a referência completa do idioma, consulte o manual jq.

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

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

Resolução de Problemas

À medida que você cria caminhos jq ou expressões dentro do processador de dados, há algumas coisas a ter em mente. Se tiver problemas, certifique-se de que não está a cometer um dos seguintes erros:

Não delimitando a payload

Todas as mensagens nos pipelines do processador de dados começam com uma estrutura que coloca a carga útil da mensagem em um campo de nível superior chamado payload. Embora não seja obrigatório, é uma convenção forte quando você processa mensagens para manter a carga principal dentro do payload campo à 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 a carga útil, portanto, é comum ver toda a consulta com escopo para o campo de carga útil. Você pode esquecer que as mensagens usam essa estrutura e tratam a carga como se estivesse no nível superior.

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

  • Filtre mensagens, adicione .payload | ao início da sua expressão para definir o escopo corretamente.
  • Transforme mensagens:
    • Se você não estiver dividindo a mensagem, adicione .payload |= ao início da expressão para definir o escopo da transformação.
    • Se você estiver dividindo a mensagem, adicione .payload = (.payload | <expression>) a sua <expression> para atualizar a carga especificamente enquanto permite 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 jq. Portanto, não é possível, apenas com filtros e transformações, combinar dados de várias mensagens de entrada.

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

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

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

O erro mais comum que você vê se 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 erros de compilação ou quaisquer outros erros estranhos ao chamar uma função que não faz sentido, certifique-se de que você está usando ; em vez de , separar seus argumentos.

Ordem de operações

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

Conteúdos relacionados

Consulte estes artigos para obter ajuda quando estiver usando o jq: