Querysyntaxis voor IoT Hub-berichtroutering

Artikel
03/18/2023

Met berichtroutering kunnen gebruikers verschillende gegevenstypen, waaronder telemetrieberichten van apparaten, levenscyclus-gebeurtenissen van apparaten en wijzigingsevenementen van apparaatdubbels, routeren naar verschillende eindpunten. U kunt ook uitgebreide query's op deze gegevens toepassen voordat u deze routert om de gegevens te ontvangen die voor u van belang zijn. In dit artikel wordt de IoT Hub querytaal voor berichtroutering beschreven en worden enkele veelvoorkomende querypatronen beschreven.

Notitie

Sommige van de functies die in dit artikel worden genoemd, zoals cloud-naar-apparaat-berichten, apparaatdubbels en apparaatbeheer, zijn alleen beschikbaar in de standaardlaag van IoT Hub. Zie Choose the right IoT Hub tier for your solution (De juiste IoT Hub laag voor uw oplossing kiezen) voor meer informatie over de basic- en standard/gratis IoT Hub lagen.

Met berichtroutering kunt u query's uitvoeren op de berichteigenschappen en berichttekst, evenals apparaatdubbeltags en apparaatdubbeleigenschappen. Als de berichttekst niet de JSON-indeling heeft, kan berichtroutering het bericht nog steeds routeren, maar kunnen query's niet worden toegepast op de berichttekst. Query's worden beschreven als Booleaanse expressies, waarbij, indien waar, de query slaagt en alle binnenkomende gegevens doorstuurt; anders mislukt de query en worden de binnenkomende gegevens niet doorgestuurd. Als de expressie een null- of niet-gedefinieerde waarde oplevert, wordt deze behandeld als een booleaanse onwaarwaarde en wordt een fout gegenereerd in de IoT Hub resourcelogboeken routeert. De querysyntaxis moet juist zijn om de route op te slaan en te evalueren.

Query uitvoeren op basis van berichteigenschappen

IoT Hub definieert een algemene indeling voor alle apparaat-naar-cloud-berichten voor interoperabiliteit tussen protocollen. IoT Hub gaat uit van de volgende JSON-weergave van het bericht. Systeemeigenschappen worden toegevoegd voor alle gebruikers en identificeren de inhoud van het bericht. Gebruikers kunnen selectief toepassingseigenschappen toevoegen aan het bericht. U wordt aangeraden unieke eigenschapsnamen te gebruiken, omdat IoT Hub apparaat-naar-cloud-berichten niet hoofdlettergevoelig zijn. Als u bijvoorbeeld meerdere eigenschappen met dezelfde naam hebt, verzendt IoT Hub slechts één 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}}" 
  } 
}

Systeemeigenschappen

Systeemeigenschappen helpen bij het identificeren van de inhoud en bron van de berichten, waarvan sommige worden beschreven in de volgende tabel:

Eigenschap	Type	Beschrijving
Contenttype	tekenreeks	De gebruiker geeft het inhoudstype van het bericht op. Als u query's wilt uitvoeren op de hoofdtekst van het bericht, moet deze waarde worden ingesteld op `application/JSON`.
contentEncoding	tekenreeks	De gebruiker geeft het coderingstype van het bericht op. Als de eigenschap contentType is ingesteld op `application/JSON`, zijn de toegestane `UTF-8`waarden , `UTF-16`en `UTF-32`.
iothub-connection-device-id	tekenreeks	Deze waarde wordt ingesteld door IoT Hub en geeft de id van het apparaat aan. Als u een query wilt uitvoeren, gebruikt u `$connectionDeviceId`.
iothub-connection-module-id	tekenreeks	Deze waarde wordt ingesteld door IoT Hub en identificeert de id van de edge-module. Als u een query wilt uitvoeren, gebruikt u `$connectionModuleId`.
iothub-enqueuedtime	tekenreeks	Deze waarde wordt ingesteld door IoT Hub en vertegenwoordigt de werkelijke tijd van het verzenden van het bericht in UTC. Als u een query wilt uitvoeren, gebruikt u `$enqueuedTime`.
dt-dataschema	tekenreeks	Deze waarde wordt ingesteld door IoT Hub voor apparaat-naar-cloud-berichten. Deze bevat de apparaatmodel-id die is ingesteld in de apparaatverbinding. Als u een query wilt uitvoeren, gebruikt u `$dt-dataschema`.
dt-onderwerp	tekenreeks	De naam van het onderdeel dat de apparaat-naar-cloud-berichten verzendt. Als u een query wilt uitvoeren, gebruikt u `$dt-subject`.

Zie Berichten IoT Hub maken en lezen voor meer informatie over de andere beschikbare systeemeigenschappen.

Toepassingseigenschappen

Toepassingseigenschappen zijn door de gebruiker gedefinieerde tekenreeksen die aan het bericht kunnen worden toegevoegd. Deze velden zijn optioneel.

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 IoT Hub er eerst naar in de systeemeigenschappen. Als de naam niet wordt gevonden, wordt ernaar gezocht in de eigenschappen van de toepassing. In de volgende voorbeelden ziet u hoe u een query uitvoert op systeemeigenschappen en toepassingseigenschappen.

Een query uitvoeren op de systeemeigenschap contentEncoding:

$contentEncoding = 'UTF-8'

Ga als volgende te werk om een query uit te voeren op de toepassingseigenschap processingPath:

processingPath = 'hot'

Als u deze query's wilt combineren, kunt u Boole-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 IoT Hub querytaal voor apparaat- en moduledubbels, taken en berichtroutering.

Query uitvoeren op basis van berichttekst

Als u query's wilt uitvoeren op een berichttekst, moet het bericht een JSON-indeling hebben en zijn gecodeerd in UTF-8, UTF-16 of UTF-32. De contentType systeemeigenschap moet zijn application/JSON. De contentEncoding systeemeigenschap moet een van de UTF-coderingswaarden zijn die door die systeemeigenschap worden ondersteund. Als deze systeemeigenschappen niet zijn opgegeven, evalueert IoT Hub de queryexpressie niet in de berichttekst.

In het volgende JavaScript-voorbeeld ziet u hoe u een bericht maakt met een correct gevormde 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);
});

Zie de HubRoutingSample in de Microsoft Azure IoT SDK voor .NET voor een voorbeeld van berichtcodering in C#. Dit voorbeeld is hetzelfde als in de zelfstudie Berichtroutering. Het bestand Program.cs heeft ook een methode met de naam ReadOneRowFromFile, waarmee een van de gecodeerde bestanden wordt gelezen, gedecodeerd en teruggeschreven als ASCII, zodat u het kunt lezen.

Query-expressies voor berichttekst

Een query op een berichttekst moet worden voorafgegaan door $body. U kunt een hoofdtekstverwijzing, hoofdtekstmatrixverwijzing of meerdere hoofdtekstverwijzingen gebruiken in de queryexpressie. Uw queryexpressie kan ook een hoofdtekstreferentie combineren met een verwijzing naar de eigenschappen van het berichtsysteem of een verwijzing naar eigenschappen van een berichttoepassing. De volgende voorbeelden zijn bijvoorbeeld allemaal 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 de nettolading van een dubbele melding wilt filteren op basis van wat er is gewijzigd, voert u de query uit op de hoofdtekst van het bericht. Als u bijvoorbeeld wilt filteren wanneer er een gewenste eigenschapswijziging optreedt 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)

Query op basis van apparaat- of moduledubbel

Met berichtroutering kunt u een query 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 de bijbehorende apparaten. Dubbelquery's voor berichten die afkomstig zijn van apparaatmodules (bijvoorbeeld van IoT Edge modules) voeren query's uit op de moduledubbel en niet op de bijbehorende apparaatdubbel.

Dubbelquery-expressies

Een query op een apparaatdubbel of moduledubbel moet worden voorafgegaan door $twin. Uw queryexpressie kan ook een dubbele tag of eigenschapsreferentie combineren met een hoofdtekstreferentie, een verwijzing naar berichtsysteemeigenschappen of een verwijzing naar eigenschappen van een berichttoepassing. U wordt aangeraden unieke namen te gebruiken in tags en eigenschappen, omdat de query niet hoofdlettergevoelig is. Deze aanbeveling is van toepassing op zowel apparaatdubbels als moduledubbels. We raden u ook aan om te voorkomen twindat u , $twin, bodyof $body als eigenschapsnamen gebruikt. De volgende voorbeelden zijn bijvoorbeeld allemaal 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: ()<>@,;:\"/?={}.

Volgende stappen

Meer informatie over berichtroutering.
Probeer de zelfstudie voor berichtroutering.