Sintaxe de consulta do encaminhamento de mensagens do Hub IoT

O encaminhamento de mensagens permite que os utilizadores encaminhem diferentes tipos de dados, incluindo mensagens de telemetria do dispositivo, eventos de ciclo de vida do dispositivo e eventos de alteração de dispositivo duplo, para vários pontos finais. Também pode aplicar consultas avançadas a estes dados antes de encaminhá-las para receber os dados que lhe interessam. Este artigo descreve a linguagem de consulta de encaminhamento de mensagens Hub IoT e fornece alguns padrões de consulta comuns.

Nota

Algumas das funcionalidades mencionadas neste artigo, como mensagens da cloud para o dispositivo, dispositivos duplos e gestão de dispositivos, só estão disponíveis na camada padrão de Hub IoT. Para obter mais informações sobre as camadas de Hub IoT básicas e padrão/gratuitas, consulte Escolher o escalão de Hub IoT adequado para a sua solução.

O encaminhamento de mensagens permite-lhe consultar as propriedades da mensagem e o corpo da mensagem, bem como as etiquetas do dispositivo duplo e as propriedades do dispositivo duplo. Se o corpo da mensagem não estiver no formato JSON, o encaminhamento de mensagens ainda pode encaminhar a mensagem, mas as consultas não podem ser aplicadas ao corpo da mensagem. As consultas são descritas como expressões booleanas em que, se for verdadeira, a consulta é bem-sucedida e encaminha todos os dados recebidos; caso contrário, a consulta falha e os dados recebidos não são encaminhados. Se a expressão for avaliada como um valor nulo ou indefinido, é tratada como um valor booleano falso e gera um erro no Hub IoT encaminha os registos de recursos. A sintaxe da consulta tem de estar correta para que a rota seja guardada e avaliada.

Consulta com base nas propriedades da mensagem

Hub IoT define um formato comum para todas as mensagens do dispositivo para a cloud para interoperabilidade entre protocolos. Hub IoT assume a seguinte representação JSON da mensagem. As propriedades do sistema são adicionadas a todos os utilizadores e identificam o conteúdo da mensagem. Os utilizadores podem adicionar seletivamente propriedades da aplicação à mensagem. Recomendamos que utilize nomes de propriedade exclusivos porque Hub IoT mensagens do dispositivo para a cloud não são sensíveis a maiúsculas e minúsculas. Por exemplo, se tiver várias propriedades com o mesmo nome, 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 estão descritas na seguinte tabela:

Propriedade	Tipo	Description
contentType	string	O utilizador especifica o tipo de conteúdo da mensagem. Para permitir a consulta no corpo da mensagem, este valor deve ser definido como application/JSON.
contentEncoding	string	O utilizador especifica o tipo de codificação da mensagem. Se a propriedade contentType estiver definida como application/JSON, os valores permitidos são UTF-8, UTF-16e UTF-32.
iothub-connection-device-id	string	Este valor é definido por Hub IoT e identifica o ID do dispositivo. Para consultar, utilize $connectionDeviceId.
iothub-connection-module-id	string	Este valor é definido por Hub IoT e identifica o ID do módulo edge. Para consultar, utilize $connectionModuleId.
iothub-enqueuedtime	string	Este valor é definido por Hub IoT e representa a hora real de colocar a mensagem em fila de espera em UTC. Para consultar, utilize $enqueuedTime.
dt-dataschema	string	Este valor é definido por Hub IoT em mensagens do dispositivo para a cloud. Contém o ID do modelo de dispositivo definido na ligação do dispositivo. Para consultar, utilize $dt-dataschema.
dt-subject	string	O nome do componente que está a enviar as mensagens do dispositivo para a cloud. Para consultar, utilize $dt-subject.

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

Propriedades da aplicação

As propriedades da aplicação são cadeias definidas pelo utilizador que podem ser adicionadas à mensagem. Estes campos são opcionais.

Expressões de consulta de propriedades de mensagens

Uma consulta nas propriedades do sistema de mensagens tem de ser prefixada com o $ símbolo. As consultas nas propriedades da aplicação são acedidas com o respetivo nome e não devem ser prefixadas com o $símbolo. Se um nome de propriedade de aplicação começar com $, Hub IoT primeiro procura-o nas propriedades do sistema e, se não for encontrado, irá procurá-lo nas propriedades da aplicação. Os exemplos seguintes mostram como consultar as propriedades do sistema e as propriedades da aplicação.

Para consultar o conteúdo da propriedade do sistemaEncodificação:

$contentEncoding = 'UTF-8'

Para consultar o processingPath da propriedade da aplicação:

processingPath = 'hot'

Para combinar estas consultas, pode utilizar expressões e funções booleanas:

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

É fornecida uma lista completa dos operadores e funções suportados na secção expressão e condições do Hub IoT linguagem de consulta para dispositivos e módulos duplos, tarefas e encaminhamento de mensagens.

Consulta com base no corpo da mensagem

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

O exemplo de JavaScript seguinte 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#, veja HubRoutingSample fornecido no SDK IoT do Microsoft Azure para .NET. Este exemplo é o mesmo utilizado no tutorial de Encaminhamento de Mensagens. O ficheiro Program.cs também tem um método denominado ReadOneRowFromFile, que lê um dos ficheiros codificados, descodifica-o e escreve-o novamente como ASCII para que possa lê-lo.

Expressões de consulta do corpo da mensagem

Uma consulta num corpo de mensagem tem de ser prefixada com $body. Pode utilizar uma referência do corpo, uma referência de matriz do corpo ou várias referências de corpo na expressão de consulta. A expressão de consulta também pode combinar uma referência corporal com uma referência de propriedades do sistema de mensagens ou uma referência de propriedades da aplicação de mensagens. Por exemplo, os exemplos seguintes 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'

Só pode executar consultas e funções em propriedades na referência do corpo. Não pode executar consultas ou funções em toda a referência do corpo. Por exemplo, a seguinte consulta não é suportada e devolve undefined:

$body[0] = 'Feb'

Para filtrar um payload de notificação duplo com base no que mudou, execute a consulta no corpo da mensagem. Por exemplo, para filtrar quando existe uma alteração de sendFrequency propriedade pretendida e o valor for superior a 10:

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

Para filtrar mensagens que contenham uma alteração de propriedade, independentemente do valor da propriedade, pode utilizar a is_defined() função (quando o valor é um tipo primitivo):

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

Consulta com base no dispositivo ou módulo duplo

O encaminhamento de mensagens permite-lhe consultar em propriedades e etiquetas de duplo dispositivo ou módulo duplo , que são objetos JSON. O exemplo seguinte ilustra um dispositivo duplo com etiquetas 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 etiquetas duplas dos respetivos dispositivos correspondentes. Consultas duplas para mensagens provenientes de módulos de dispositivo (por exemplo, de módulos IoT Edge) relativamente ao módulo duplo e não ao dispositivo duplo correspondente.

Expressões de consulta duplos

Uma consulta num dispositivo duplo ou módulo duplo tem de ser prefixada com $twin. A expressão de consulta também pode combinar uma etiqueta de duplo 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 da aplicação de mensagens. Recomendamos a utilização de nomes exclusivos em etiquetas e propriedades porque a consulta não é sensível a maiúsculas e minúsculas. Esta recomendação aplica-se tanto aos dispositivos duplos como aos módulos duplos. Também recomendamos que evite utilizar twin, $twin, bodyou $body como nomes de propriedades. Por exemplo, os exemplos seguintes 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 encaminhamento não suportam a utilização de espaço em branco ou qualquer um dos seguintes carateres em nomes de propriedades, o caminho do corpo da mensagem ou o caminho do dispositivo/módulo duplo: ()<>@,;:\"/?={}.

Passos seguintes

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