Esaminare le query di routing dei messaggi
Il routing dei messaggi consente agli utenti di instradare diversi tipi di dati, inclusi i messaggi di telemetria del dispositivo, gli eventi del ciclo di vita del dispositivo e gli eventi di modifica dei dispositivi gemelli a vari endpoint. Il routing dei messaggi dell'hub IoT di Azure offre una funzionalità di query per filtrare i dati prima di instradarli agli endpoint.
Un singolo messaggio può corrispondere alla condizione in più query di routing, nel qual caso l'hub IoT di Azure recapita il messaggio all'endpoint associato a ogni query corrispondente. Anche l'hub IoT di Azure deduplica automaticamente il recapito dei messaggi, quindi se un messaggio corrisponde a più query con la stessa destinazione, viene scritto una sola volta in tale destinazione.
Ogni query di routing configurata ha le proprietà seguenti:
Proprietà
Descrizione
Name
Il nome univoco che identifica la query.
Origine
L'origine del flusso dati su cui intervenire. Ad esempio, i dati di telemetria del dispositivo.
Condizione
Espressione di query per la query di routing eseguita sulle proprietà dell'applicazione del messaggio, proprietà di sistema, corpo del messaggio, tag del dispositivo gemello e proprietà del dispositivo gemello per determinare se si tratta di una corrispondenza per l'endpoint.
Endpoint
Nome dell'endpoint in cui l'hub IoT di Azure invia messaggi che corrispondono alla query. È consigliabile scegliere un endpoint nella stessa area dell'hub IoT di Azure.
Sintassi delle query di routing dei messaggi
Il routing dei messaggi consente di eseguire query sulle proprietà dei messaggi e sul corpo del messaggio, nonché sui tag e sulle proprietà del dispositivo gemello. Se il corpo del messaggio non è in formato JSON, il routing dei messaggi può comunque instradare il messaggio, ma le query non possono essere applicate al corpo del messaggio. Le query vengono descritte come espressioni booleane in cui, se true, la query ha esito positivo e instrada tutti i dati in ingresso; in caso contrario, la query ha esito negativo e i dati in ingresso non vengono instradati. Se l'espressione restituisce un valore null o non definito, viene considerato come valore booleano false e genera un errore nei log delle risorse dell'hub IoT di Azure. La sintassi di query deve essere corretta per la route per essere salvata e valutata.
Routing messaggi di query basato sulle proprietà del messaggio
L'hub IoT di Azure definisce un formato comune per tutta la messaggistica da dispositivo a cloud per l'interoperabilità tra protocolli. L'hub IoT di Azure presuppone la rappresentazione JSON seguente del messaggio.
- Le proprietà di sistema (systemProperties) vengono aggiunte per tutti gli utenti e identificano il contenuto del messaggio.
- Gli utenti possono facoltativamente aggiungere proprietà dell'applicazione (appProperties) al messaggio. Le proprietà dell'applicazione sono stringhe definite dall'utente. È consigliabile usare nomi di proprietà univoci poiché la messaggistica da dispositivo a cloud dell'hub IoT di Azure non fa distinzione tra maiuscole e minuscole. Ad esempio, se si hanno più proprietà con lo stesso nome, l'hub IoT di Azure invierà solo una delle proprietà.
{
"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}}"
}
}
Espressioni di query delle proprietà del messaggio
Una query sulle proprietà di sistema del messaggio richiede come prefisso il simbolo $. Viene eseguito l'accesso alle query sulle proprietà dell'applicazione con il relativo nome e non devono essere precedute dal simbolo $. Se il nome di una proprietà dell'applicazione inizia con $, l'hub IoT di Azure lo cerca nelle proprietà di sistema e non viene trovato, quindi cerca nelle proprietà dell'applicazione. Negli esempi seguenti viene illustrato come eseguire query sulle proprietà di sistema e sulle proprietà dell'applicazione.
Per eseguire query sulla proprietà di sistema contentEncoding:
$contentEncoding = 'UTF-8'
Per eseguire una query una proprietà di applicazione processingPath:
processingPath = 'hot'
Per combinare queste query, è possibile usare funzioni ed espressioni booleane:
$contentEncoding = 'UTF-8' AND processingPath = 'hot'
Un elenco completo di operatori e funzioni supportati è disponibile nella sezione Espressione e condizioni di Linguaggio di query dell'hub IoT per dispositivi e moduli gemelli, processi e routing di messaggi.
Query di routing dei messaggi in base al corpo del messaggio
Per abilitare l'esecuzione di query nel corpo del messaggio, il messaggio deve essere in formato JSON codificato in UTF-8, UTF-16 o UTF-32. Il contentType deve essere impostato su application/JSON. La proprietà di sistema contentEncoding deve essere una delle codifiche UTF supportate da tale proprietà di sistema. Se queste proprietà non vengono specificate, l'hub IoT di Azure non valuterà l'espressione di query nel corpo del messaggio.
L'esempio seguente mostra come creare un messaggio con un corpo JSON correttamente formattato e codificato:
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);
});
Espressioni di query per la query di routing dei messaggi in base al corpo del messaggio
Una query nel corpo di un messaggio deve essere preceduta da $body. Nell'espressione di query è possibile usare un riferimento al corpo, un riferimento a una matrice del corpo o riferimenti multipli al corpo. L'espressione di query può anche combinare un riferimento al corpo con un riferimento alle proprietà del sistema dei messaggi o un riferimento alle proprietà dell'applicazione del messaggio. Ad esempio, di seguito sono riportate tutte le espressioni di query valide:
$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'
È possibile eseguire query e funzioni solo sulle proprietà nel riferimento al corpo. Non è possibile eseguire query o funzioni sull'intero riferimento al corpo. Ad esempio, la query seguente non è supportata e restituisce undefined:
$body[0] = 'Feb'
Per filtrare un payload di notifica gemello in base a quanto modificato, eseguire la query sul corpo del messaggio. Ad esempio, per filtrare quando è presente una modifica sendFrequency della proprietà desiderata e il valore è maggiore di 10:
`$body.properties.desired.telemetryConfig.sendFrequency > 10`
Per filtrare i messaggi che contengono una modifica della proprietà, indipendentemente dal valore della proprietà, è possibile usare la funzione is_defined() (quando il valore è un tipo primitivo):
`is_defined($body.properties.desired.telemetryConfig.sendFrequency)`
Query di routing dei messaggi basata sul dispositivo gemello
Il routing dei messaggi consente di eseguire query su tag e proprietà del dispositivo gemello o del modulo gemello, ovvero oggetti JSON. L'esempio seguente illustra un dispositivo gemello con tag e proprietà:
{
"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
I moduli non ereditano tag gemelli dai dispositivi corrispondenti. Query dei dispositivi gemelli per i messaggi provenienti da moduli del dispositivo (ad esempio, dai moduli IoT Edge) su un modulo gemello e non sul dispositivo gemello corrispondente.
Espressioni di query per la query di routing dei messaggi in base al dispositivo gemello
Una query nelle proprietà del dispositivo gemello deve essere preceduta da $twin. L'espressione di query può anche combinare un tag gemello o un riferimento a una proprietà con un riferimento al corpo,un riferimento alle proprietà del sistema di messaggi o un riferimento alle proprietà dell'applicazione del messaggio. È consigliabile usare nomi univoci in tag e proprietà perché la query non fa distinzione tra maiuscole e minuscole. È inoltre consigliabile evitare di usare twin, $twin, bodyo $body, come nomi di proprietà. Ad esempio, di seguito sono riportate tutte le espressioni di query valide:
$twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$twin.tags.deploymentLocation.floor = 1
Limiti
Le query di routing non supportano l'uso di spazi vuoti o di uno dei caratteri seguenti nei nomi delle proprietà, nel percorso del corpo del messaggio o nel percorso del dispositivo/modulo gemello: ()<>@,;:\"/?={}.