Berichtrouteringsquery's onderzoeken
Met berichtroutering kunnen gebruikers verschillende gegevenstypen, waaronder telemetrieberichten van apparaten, gebeurtenissen van de levenscyclus van apparaten en wijzigingsevenementen van apparaatdubbels, routeren naar verschillende eindpunten. Azure IoT Hub-berichtroutering biedt een queryfunctie om de gegevens te filteren voordat deze naar de eindpunten worden gerouteerd.
Eén bericht kan overeenkomen met de voorwaarde voor meerdere routeringsquery's. In dat geval levert Azure IoT Hub het bericht aan het eindpunt dat is gekoppeld aan elke overeenkomende query. Azure IoT Hub ontdubbelt ook automatisch de bezorging van berichten, dus als een bericht overeenkomt met meerdere query's met dezelfde bestemming, wordt het slechts eenmaal naar die bestemming geschreven.
Elke routeringsquery die u configureert, heeft de volgende eigenschappen:
Eigenschappen
Beschrijving
Naam
De unieke naam waarmee de query wordt geïdentificeerd.
Bron
De oorsprong van de gegevensstroom waarop moet worden gereageerd. Bijvoorbeeld apparaattelemetrie.
Conditie
De query-expressie voor de routeringsquery die wordt uitgevoerd op basis van de eigenschappen van de berichttoepassing, systeemeigenschappen, berichttekst, apparaatdubbeltags en apparaatdubbeleigenschappen om te bepalen of deze overeenkomt met het eindpunt.
Eindpunt
De naam van het eindpunt waar Azure IoT Hub berichten verzendt die overeenkomen met de query. U wordt aangeraden een eindpunt te kiezen in dezelfde regio als uw Azure IoT-hub.
Querysyntaxis voor berichtroutering
Met berichtroutering kunt u query's uitvoeren op de berichteigenschappen en hoofdtekst van het bericht, evenals tags van apparaatdubbels en eigenschappen van apparaatdubbels. Als de berichttekst niet de JSON-indeling heeft, kan berichtroutering het bericht nog steeds routeren, maar kunnen query's niet worden toegepast op de hoofdtekst van het bericht. Query's worden beschreven als Boole-expressies waarbij, indien waar, de query slaagt en alle binnenkomende gegevens routeert; anders mislukt de query en worden de binnenkomende gegevens niet gerouteerd. Als de expressie resulteert in een null- of niet-gedefinieerde waarde, wordt deze beschouwd als een Booleaanse onwaar-waarde en wordt er een fout gegenereerd in de Azure IoT Hub-resourcelogboeken. De querysyntaxis moet juist zijn om de route op te slaan en te evalueren.
Query voor berichtroutering op basis van berichteigenschappen
Azure IoT Hub definieert een algemene indeling voor alle apparaat-naar-cloud-berichten voor interoperabiliteit tussen protocollen. Azure IoT Hub gaat uit van de volgende JSON-weergave van het bericht.
- Systeemeigenschappen (systemProperties) worden toegevoegd voor alle gebruikers en identificeren de inhoud van het bericht.
- Gebruikers kunnen eventueel toepassingseigenschappen (appProperties) toevoegen aan het bericht. Toepassingseigenschappen zijn door de gebruiker gedefinieerde tekenreeksen. Het is raadzaam om unieke eigenschapsnamen te gebruiken omdat Azure IoT Hub device-to-cloud messaging niet hoofdlettergevoelig is. Als u bijvoorbeeld meerdere eigenschappen met dezelfde naam hebt, verzendt Azure IoT Hub slechts een van de eigenschappen.
{
"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}}"
}
}
Query-expressies voor berichteigenschappen
Een query op berichtsysteemeigenschappen moet worden voorafgegaan door het $ symbool. Query's op toepassingseigenschappen worden geopend met hun naam en mogen niet worden voorafgegaan door het $ symbool. Als de naam van een toepassingseigenschap begint met $, zoekt Azure IoT Hub ernaar in de systeemeigenschappen en wordt deze niet gevonden. Vervolgens wordt deze in de eigenschappen van de toepassing gezocht. In de volgende voorbeelden ziet u hoe u query's kunt uitvoeren op systeemeigenschappen en toepassingseigenschappen.
Query's uitvoeren op system property contentEncoding:
$contentEncoding = 'UTF-8'
Query's uitvoeren op toepassingseigenschap processingPath:
processingPath = 'hot'
Als u deze query's wilt combineren, kunt u Booleaanse expressies en functies gebruiken:
$contentEncoding = 'UTF-8' AND processingPath = 'hot'
Een volledige lijst met ondersteunde operators en functies vindt u in de sectie expressie en voorwaarden van de IoT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering.
Query voor berichtroutering op basis van berichttekst
Als u query's wilt inschakelen voor de berichttekst, moet het bericht zich in een JSON-gecodeerd in UTF-8, UTF-16 of UTF-32. De contentType moet worden ingesteld op application/JSON. De contentEncoding systeemeigenschap moet een van de ondersteunde UTF-coderingen zijn die door die systeemeigenschap worden ondersteund. Als deze eigenschappen niet zijn opgegeven, evalueert Azure IoT Hub de query-expressie niet in de berichttekst.
In het volgende voorbeeld ziet u hoe u een bericht maakt met een correct opgemaakte en gecodeerde JSON-hoofdtekst:
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);
});
Query-expressies voor berichtrouteringsquery op basis van de berichttekst
Een query op een berichttekst moet worden voorafgegaan door $body. U kunt een hoofdtekstverwijzing, hoofdmatrixverwijzing of meerdere hoofdtekstverwijzingen in de query-expressie gebruiken. Uw query-expressie kan ook een hoofdtekstreferentie combineren met een verwijzing naar berichtsysteemeigenschappen of een verwijzing naar eigenschappen van een berichttoepassing. Het volgende zijn bijvoorbeeld alle geldige query-expressies:
$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'
U kunt query's en functies alleen uitvoeren op eigenschappen in de hoofdtekstverwijzing. U kunt geen query's of functies uitvoeren op de volledige hoofdtekstverwijzing. De volgende query wordt bijvoorbeeld niet ondersteund en retourneert undefined:
$body[0] = 'Feb'
Als u een nettolading van een dubbelmelding wilt filteren op basis van wat er is gewijzigd, voert u de query uit op de berichttekst. Als u bijvoorbeeld wilt filteren wanneer er een gewenste eigenschapswijziging is ingeschakeld sendFrequency en de waarde groter is dan 10:
`$body.properties.desired.telemetryConfig.sendFrequency > 10`
Als u berichten wilt filteren die een eigenschapswijziging bevatten, ongeacht de waarde van de eigenschap, kunt u de is_defined() functie gebruiken (wanneer de waarde een primitief type is):
`is_defined($body.properties.desired.telemetryConfig.sendFrequency)`
Berichtrouteringsquery op basis van apparaatdubbel
Met berichtroutering kunt u query's uitvoeren op tags en eigenschappen van apparaatdubbels of moduledubbels. Dit zijn JSON-objecten. In het volgende voorbeeld ziet u een apparaatdubbel met tags en eigenschappen:
{
"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
}
}
}
Notitie
Modules nemen geen dubbeltags over van hun bijbehorende apparaten. Dubbelquery's voor berichten die afkomstig zijn van apparaatmodules (bijvoorbeeld van IoT Edge-modules) voor de moduledubbel en niet de bijbehorende apparaatdubbel.
Query-expressies voor berichtrouteringsquery op basis van apparaatdubbel
Een query op eigenschappen van apparaatdubbels moet worden voorafgegaan door $twin. Uw query-expressie kan ook een dubbeltag- of eigenschapsreferentie combineren met een hoofdtekstreferentie, een verwijzing naar berichtsysteemeigenschappen of een verwijzing naar de eigenschappen van een berichttoepassing. We raden u aan unieke namen te gebruiken in tags en eigenschappen, omdat de query niet hoofdlettergevoelig is. We raden u ook aan om het gebruik twinvan , $twinof body, $bodyals eigenschapsnamen te vermijden. Het volgende zijn bijvoorbeeld alle geldige query-expressies:
$twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$twin.tags.deploymentLocation.floor = 1
Beperkingen
Routeringsquery's bieden geen ondersteuning voor het gebruik van witruimte of een van de volgende tekens in eigenschapsnamen, het hoofdtekstpad van het bericht of het pad van de apparaat-/moduledubbel: ()<>@,;:\"/?={}.