Converter dados usando conversões de fluxo de dados

Você pode usar conversões de fluxo de dados para transformar dados nas Operações do Azure IoT. O elemento de conversão em um fluxo de dados é usado para calcular valores para campos de saída. Você pode usar campos de entrada, operações disponíveis, tipos de dados e conversões de tipo em conversões de fluxo de dados.

O elemento de conversão de fluxo de dados é usado para calcular valores para campos de saída:

inputs: [
  '*.Max' // - $1
  '*.Min' // - $2
]
output: 'ColorProperties.*'
expression: '($1 + $2) / 2'

- inputs:
  - *.Max   # - $1
  - *.Min   # - $2
  output: ColorProperties.*
  expression: ($1 + $2) / 2

Há vários aspetos para entender sobre conversões:

• Referência a campos de entrada: Como referenciar valores de campos de entrada na fórmula de conversão.
• Operações disponíveis: operações que podem ser utilizadas em conversões. Por exemplo, adição, subtração, multiplicação e divisão.
• Tipos de dados: tipos de dados que uma fórmula pode processar e manipular. Por exemplo, inteiro, ponto flutuante e string.
• Conversões de tipo: como os tipos de dados são convertidos entre os valores dos campos de entrada, a avaliação da fórmula e os campos de saída.

Campos de entrada

Em conversões, as fórmulas podem operar em valores estáticos como um número como 25 ou parâmetros derivados de campos de entrada. Um mapeamento define esses campos de entrada que a fórmula pode acessar. Cada campo é referenciado de acordo com a sua ordem na lista de entradas:

inputs: [
  '*.Max'      // - $1
  '*.Min'      // - $2
  '*.Mid.Avg'  // - $3
  '*.Mid.Mean' // - $4
]
output: 'ColorProperties.*'
expression: '($1, $2, $3, $4)'

- inputs:
  - *.Max        # - $1
  - *.Min        # - $2
  - *.Mid.Avg    # - $3
  - *.Mid.Mean   # - $4
  output: ColorProperties.*
  expression: ($1, $2, $3, $4)

Neste exemplo, a conversão resulta em uma matriz contendo os valores de [Max, Min, Mid.Avg, Mid.Mean]. Os comentários no arquivo YAML (# - $1, # - $2) são opcionais, mas ajudam a esclarecer a conexão entre cada propriedade de campo e seu papel na fórmula de conversão.

Tipos de dados

Diferentes formatos de serialização suportam vários tipos de dados. Por exemplo, JSON oferece alguns tipos primitivos: string, number, Boolean e null. Também inclui matrizes desses tipos primitivos.

Quando o mapeador lê uma propriedade de entrada, ele a converte em um tipo interno. Essa conversão é necessária para manter os dados na memória até que sejam gravados em um campo de saída. A conversão para um tipo interno acontece independentemente de os formatos de serialização de entrada e saída serem os mesmos.

A representação interna utiliza os seguintes tipos de dados:

Campos de registo de entrada

Quando um campo de registro de entrada é lido, seu tipo subjacente é convertido em uma dessas variantes de tipo interno. A representação interna é versátil o suficiente para lidar com a maioria dos tipos de entrada com pouca ou nenhuma conversão.

Para alguns formatos, são usados tipos substitutos. Por exemplo, JSON não tem um datetime tipo e, em vez disso, armazena datetime valores como cadeias de caracteres formatadas de acordo com ISO8601. Quando o mapeador lê tal campo, a representação interna permanece uma cadeia de caracteres.

Campos de registro de saída

O mapeador foi projetado para ser flexível, convertendo tipos internos em tipos de saída para acomodar cenários em que os dados vêm de um formato de serialização com um sistema de tipo limitado. Os exemplos a seguir mostram como as conversões são tratadas:

• Tipos numéricos: Estes tipos podem ser convertidos em outras representações, mesmo que isso signifique perder a precisão. Por exemplo, um número de ponto flutuante de 64 bits (f64) pode ser convertido em um inteiro de 32 bits (i32).
• Strings para números: Se o registro de entrada contiver uma string like 123 e o campo de saída for um inteiro de 32 bits, o mapeador converte e grava o valor como um número.
• Strings para outros tipos:
  • Se o campo de saída for datetime, o mapeador tentará analisar a cadeia de caracteres como um ISO8601 formatado datetime.
  • Se o campo de saída for binary/bytes, o mapeador tentará desserializar a cadeia de caracteres de uma cadeia de caracteres codificada em base64.
• Valores booleanos:
  • Convertido em 0/1 se o campo de saída for numérico.
  • Convertido em true/false se o campo de saída for string.

Usar uma fórmula de conversão com tipos

Em mapeamentos, uma fórmula opcional pode especificar como os dados da entrada são processados antes de serem gravados no campo de saída. Se nenhuma fórmula for especificada, o mapeador copiará o campo de entrada para a saída usando o tipo interno e as regras de conversão.

Se uma fórmula for especificada, os tipos de dados disponíveis para uso em fórmulas serão limitados a:

• Números inteiros
• Números de vírgula flutuante
• Cadeias
• Booleanos
• Matrizes dos tipos anteriores
• Valor em falta

Map e byte não pode participar de fórmulas.

Os tipos relacionados ao tempo (datetime, time, e duration) são convertidos em valores inteiros que representam o tempo em segundos. Após a avaliação da fórmula, os resultados são armazenados na representação interna e não convertidos novamente. Por exemplo, datetime convertido em segundos permanece um inteiro. Se o valor for usado em datetime campos, um método de conversão explícito deve ser aplicado. Um exemplo é a conversão do valor em uma cadeia de caracteres ISO8601 que é convertida automaticamente para o datetime tipo do formato de serialização de saída.

Usar tipos irregulares

Considerações especiais se aplicam a tipos como matrizes e valor ausente.

Matrizes

As matrizes podem ser processadas usando funções de agregação para calcular um único valor a partir de vários elementos. Por exemplo, usando o registro de entrada:

{
  "Measurements": [2.34, 12.3, 32.4]
}

Com o mapeamento:

inputs: [
  'Measurements' // - $1
]
output: 'Measurement'
expression: 'min($1)'

- inputs:
  - Measurements # - $1
  output: Measurement
  expression: min($1)

Esta configuração seleciona o Measurements menor valor da matriz para o campo de saída.

As matrizes também podem ser criadas a partir de vários valores únicos:

inputs: [
  'minimum' // - - $1
  'maximum' // - - $2
  'average' // - - $3
  'mean'    // - - $4
]
output: 'stats'
expression: '($1, $2, $3, $4)'

- inputs:
  - minimum  # - - $1
  - maximum  # - - $2
  - average  # - - $3
  - mean     # - - $4
  output: stats
  expression: ($1, $2, $3, $4)

Esse mapeamento cria uma matriz que contém o mínimo, o máximo, a média e a média.

Valor em falta

O valor ausente é um tipo especial usado em cenários, como:

• Manipulação de campos ausentes na entrada, fornecendo um valor alternativo.
• Remoção condicional de um campo com base na sua presença.

Exemplo de mapeamento que usa um valor ausente:

{
  "Employment": {      
    "Position": "Analyst",
    "BaseSalary": 75000,
    "WorkingHours": "Regular"
  }
}

O registro de entrada contém o BaseSalary campo, mas possivelmente isso é opcional. Digamos que, se o campo estiver faltando, um valor deve ser adicionado a partir de um conjunto de dados de contextualização:

{
  "Position": "Analyst",
  "BaseSalary": 70000,
  "WorkingHours": "Regular"
}

Um mapeamento pode verificar se o campo está presente no registro de entrada. Se o campo for encontrado, a saída receberá esse valor existente. Caso contrário, a saída receberá o valor do conjunto de dados de contexto. Por exemplo:

inputs: [
  'BaseSalary' // - - - - - - - - - - - $1
  '$context(position).BaseSalary' //  - $2
]
output: 'BaseSalary'
expression: 'if($1 == (), $2, $1)'

- inputs:
  - BaseSalary  # - - - - - - - - - - $1
  - $context(position).BaseSalary # - $2
  output: BaseSalary
  expression: if($1 == (), $2, $1)

O conversion usa a if função que tem três parâmetros:

• O primeiro parâmetro é uma condição. No exemplo, ele verifica se o BaseSalary campo do campo de entrada (aliased como $1) é o valor ausente.
• O segundo parâmetro é o resultado da função se a condição no primeiro parâmetro for verdadeira. Neste exemplo, é o BaseSalary campo do conjunto de dados de contextualização (aliased como $2).
• O terceiro parâmetro é o valor para a condição se o primeiro parâmetro for false.

Funções disponíveis

Os fluxos de dados fornecem um conjunto de funções internas que podem ser usadas em fórmulas de conversão. Essas funções podem ser usadas para executar operações comuns, como aritmética, comparação e manipulação de cadeia de caracteres. As funções disponíveis são:

Funções de conversão

Os fluxos de dados fornecem várias funções de conversão incorporadas para conversões de unidades comuns, como temperatura, pressão, comprimento, peso e volume. Seguem-se alguns exemplos:

As conversões inversas também são suportadas:

Além disso, você pode definir suas próprias funções de conversão usando fórmulas matemáticas básicas. O sistema suporta operadores como adição (+), subtração (-), multiplicação (*) e divisão (/). Esses operadores seguem regras padrão de precedência, que podem ser ajustadas entre parênteses para garantir a ordem correta das operações. Isso permite que você personalize as conversões de unidade para atender a necessidades específicas.

Operadores disponíveis por precedência

Como Exponentiation tem a precedência mais alta, ela é executada primeiro, a menos que parênteses substituam esta ordem:

• $1 * 2 ^ 3 é interpretado como $1 * 8 porque a parte é executada primeiro, antes da 2 ^ 3 multiplicação.
• ($1 * 2) ^ 3 processa a multiplicação antes da exponenciação.

Negation e Logical not têm alta precedência, por isso sempre se apegam ao seu vizinho imediato, exceto quando a exponenciação está envolvida:

• -$1 * 2 nega $1 primeiro e depois multiplica.
• -($1 * 2) multiplica e, em seguida, nega o resultado.

Multiplication, Divisione Modulo, com a mesma precedência, são executados da esquerda para a direita, a menos que a ordem seja alterada por parênteses.

Addition e Subtraction são consideradas operações mais fracas em comparação com as operações do grupo anterior:

• $1 + 2 * 3 resulta em $1 + 6 porque 2 * 3 é executado primeiro devido à maior precedência de multiplication.
• ($1 + 2) * 3prioriza antes Multiplicationde Addition .

Comparisons operar em valores numéricos, booleanos e de cadeia de caracteres. Como eles têm menor precedência do que os operadores aritméticos, não são necessários parênteses para comparar os resultados de forma eficaz:

• $1 * 2 <= $2 é equivalente a ($1 * 2) <= $2.

Os operadores lógicos são usados para encadear condições:

• $1 > 100 && $2 > 200