Sintaxe de consulta do encaminhamento de mensagens do Hub IoT

Artigo
06/13/2024

O roteamento de mensagens permite que os usuários roteiem diferentes tipos de dados, incluindo mensagens de telemetria de dispositivo, eventos de ciclo de vida do dispositivo e eventos de alteração de gêmeos de dispositivo, para vários pontos de extremidade. Você também pode aplicar consultas avançadas a esses dados antes de roteá-los para receber os dados que são importantes para você. Este artigo descreve a linguagem de consulta de roteamento de mensagens do Hub IoT e fornece alguns padrões de consulta comuns.

Nota

Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, gêmeos de dispositivo e gerenciamento de dispositivos, estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.

O roteamento de mensagens permite que você consulte as propriedades da mensagem e o corpo da mensagem, bem como as tags gêmeas do dispositivo e as propriedades gêmeas do dispositivo. Se o corpo da mensagem não estiver no formato JSON, o roteamento da mensagem ainda poderá roteá-la, mas as consultas não poderão ser aplicadas ao corpo da mensagem. As consultas são descritas como expressões booleanas onde, se verdadeiras, a consulta é bem-sucedida e roteia todos os dados recebidos; caso contrário, a consulta falhará e os dados de entrada não serão roteados. Se a expressão for avaliada como um valor nulo ou indefinido, ela será tratada como um valor falso booleano e gerará um erro nos logs de recursos de rotas do Hub IoT. A sintaxe da consulta deve estar correta para que a rota seja salva e avaliada.

Consulta baseada nas propriedades da mensagem

O Hub IoT define um formato comum para todas as mensagens de dispositivo para nuvem para interoperabilidade entre protocolos. O Hub IoT assume a seguinte representação JSON da mensagem. As propriedades do sistema são adicionadas para todos os usuários e identificam o conteúdo da mensagem. Os usuários podem adicionar seletivamente propriedades do aplicativo à mensagem. Recomendamos o uso de nomes de propriedade exclusivos porque as mensagens de dispositivo para nuvem do Hub IoT não diferenciam maiúsculas de minúsculas. Por exemplo, se você tiver várias propriedades com o mesmo nome, o Hub IoT enviará apenas uma das propriedades.

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

Propriedades do sistema

As propriedades do sistema ajudam a identificar o conteúdo e a origem das mensagens, algumas das quais são descritas na tabela a seguir:

Propriedade	Type	Description
contentType	string	O usuário especifica o tipo de conteúdo da mensagem. Para permitir consultas no corpo da mensagem, esse valor deve ser definido como `application/JSON`.
contentEncoding	string	O usuário especifica o tipo de codificação da mensagem. Se a propriedade contentType estiver definida como `application/JSON`, os valores permitidos serão `UTF-8`, `UTF-16`e `UTF-32`.
iothub-connection-device-id	string	Esse valor é definido pelo Hub IoT e identifica a ID do dispositivo. Para consultar, use `$connectionDeviceId`.
iothub-conexão-módulo-id	string	Esse valor é definido pelo Hub IoT e identifica a ID do módulo de borda. Para consultar, use `$connectionModuleId`.
iothub-enqueuedtime	string	Esse valor é definido pelo Hub IoT e representa o tempo real de enfileiramento da mensagem em UTC. Para consultar, use `$enqueuedTime`.
DT-DataSchema	string	Esse valor é definido pelo Hub IoT em mensagens de dispositivo para nuvem. Ele contém o ID do modelo do dispositivo definido na conexão do dispositivo. Para consultar, use `$dt-dataschema`.
dt-sujeito	string	O nome do componente que está enviando as mensagens do dispositivo para a nuvem. Para consultar, use `$dt-subject`.

Para obter mais informações sobre as outras propriedades do sistema disponíveis, consulte Criar e ler mensagens do Hub IoT.

Propriedades da aplicação

As propriedades do aplicativo são cadeias de caracteres definidas pelo usuário que podem ser adicionadas à mensagem. Estes campos são opcionais.

Expressões de consulta de propriedades de mensagem

Uma consulta nas propriedades do sistema de mensagens deve ser prefixada com o $ símbolo. As consultas nas propriedades do aplicativo são acessadas com seu nome e não devem ser prefixadas com o $símbolo. Se um nome de propriedade de aplicativo começar com $, o Hub IoT primeiro o procurará nas propriedades do sistema e, se não for encontrado, procurará por ele nas propriedades do aplicativo. Os exemplos a seguir mostram como consultar as propriedades do sistema e as propriedades do aplicativo.

Para consultar a propriedade do sistema contentEncoding:

$contentEncoding = 'UTF-8'

Para consultar a propriedade do aplicativo processingPath:

processingPath = 'hot'

Para combinar essas consultas, você pode usar expressões e funções booleanas:

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Uma lista completa de operadores e funções suportados é fornecida na seção expressão e condições da linguagem de consulta do Hub IoT para gêmeos de dispositivo e módulo, trabalhos e roteamento de mensagens.

Consulta com base no corpo da mensagem

Para habilitar a consulta em um corpo de mensagem, a mensagem deve estar em um formato JSON e codificada em UTF-8, UTF-16 ou UTF-32. A contentType propriedade system deve ser application/JSON. A contentEncoding propriedade system deve ser um dos valores de codificação UTF suportados por essa propriedade system. Se essas propriedades do sistema não forem especificadas, o Hub IoT não avaliará a expressão de consulta no corpo da mensagem.

O exemplo JavaScript a seguir mostra como criar uma mensagem com um corpo JSON devidamente formado e codificado:

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

Para obter um exemplo de codificação de mensagens em C#, consulte HubRoutingSample fornecido no SDK do Microsoft Azure IoT para .NET. Este exemplo é o mesmo usado no tutorial Roteamento de mensagens. O arquivo Program.cs também tem um método chamado ReadOneRowFromFile, que lê um dos arquivos codificados, decodifica-o e grava-o novamente como ASCII para que você possa lê-lo.

Expressões de consulta do corpo da mensagem

Uma consulta no corpo de uma mensagem precisa ser prefixada com $body. Você pode usar uma referência de corpo, referência de matriz de corpo ou várias referências de corpo na expressão de consulta. Sua expressão de consulta também pode combinar uma referência de corpo com uma referência de propriedades do sistema de mensagens ou uma referência de propriedades de aplicativo de mensagem. Por exemplo, os exemplos a seguir são todas expressões de consulta válidas:

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

Você pode executar consultas e funções somente em propriedades na referência de corpo. Não é possível executar consultas ou funções em toda a referência de corpo. Por exemplo, a seguinte consulta não é suportada e retorna undefined:

$body[0] = 'Feb'

Para filtrar uma carga de notificação dupla com base no que mudou, execute a consulta no corpo da mensagem. Por exemplo, para filtrar quando há uma alteração de propriedade desejada e sendFrequency o valor é maior que 10:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Para filtrar mensagens que contenham uma alteração de propriedade, não importa o valor da propriedade, você pode usar a is_defined() função (quando o valor é um tipo primitivo):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Consulta baseada em dispositivo ou módulo twin

O roteamento de mensagens permite que você consulte as tags e propriedades gêmeas de dispositivo ou módulo, que são objetos JSON. O exemplo a seguir ilustra um dispositivo gêmeo com tags e propriedades:

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Nota

Os módulos não herdam tags gêmeas de seus dispositivos correspondentes. Consultas gêmeas para mensagens originadas de módulos de dispositivo (por exemplo, de módulos do IoT Edge) consultam o gêmeo de módulo e não o gêmeo de dispositivo correspondente.

Expressões de consulta gêmeas

Uma consulta em um dispositivo gêmeo ou módulo gêmeo precisa ser prefixada com $twin. Sua expressão de consulta também pode combinar uma marca gêmea ou referência de propriedade com uma referência de corpo, uma referência de propriedades do sistema de mensagens ou uma referência de propriedades de aplicativo de mensagem. Recomendamos o uso de nomes exclusivos em tags e propriedades porque a consulta não diferencia maiúsculas de minúsculas. Esta recomendação aplica-se tanto a gémeos de dispositivos como a gémeos de módulos. Também recomendamos que você evite usar twin, $twin, body, ou $body como nomes de propriedade. Por exemplo, os exemplos a seguir são todas expressões de consulta válidas:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Limitações

As consultas de roteamento não suportam o uso de espaço em branco ou qualquer um dos seguintes caracteres em nomes de propriedade, o caminho do corpo da mensagem ou o caminho gêmeo dispositivo/módulo: ()<>@,;:\"/?={}.

Próximos passos

Saiba mais sobre o encaminhamento de mensagens.
Experimente o tutorial de roteamento de mensagens.

Partilhar via