Querysyntaxis voor IoT Hub-berichtroutering

Artikel
06/13/2024

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

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 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 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 IoT Hub-resourcelogboeken. 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 inhoud van het bericht. Gebruikers kunnen selectief toepassingseigenschappen toevoegen aan het bericht. We raden u aan om unieke eigenschapsnamen te gebruiken omdat IoT Hub-apparaat-naar-cloud-berichten niet hoofdlettergevoelig is. Als u bijvoorbeeld meerdere eigenschappen met dezelfde naam hebt, verzendt 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}}" 
  } 
}

Systeemeigenschappen

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

Eigenschap	Type	Description
contentType	tekenreeks	De gebruiker geeft het inhoudstype van het bericht op. Als u query's wilt toestaan 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`, dan zijn `UTF-8`toegestane waarden , `UTF-16`en `UTF-32`.
iothub-verbinding-apparaat-id	tekenreeks	Deze waarde wordt ingesteld door IoT Hub en identificeert de id van het apparaat. 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 enqueueren van het bericht in UTC. Als u een query wilt uitvoeren, gebruikt u `$enqueuedTime`.
dt-dataschema	tekenreeks	Deze waarde wordt ingesteld door IoT Hub op apparaat-naar-cloud-berichten. Het bevat de apparaatmodel-id die is ingesteld in de apparaatverbinding. Als u een query wilt uitvoeren, gebruikt u `$dt-dataschema`.
dt-subject	tekenreeks	De naam van het onderdeel dat de apparaat-naar-cloud-berichten verzendt. Als u een query wilt uitvoeren, gebruikt u `$dt-subject`.

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

Toepassingseigenschappen

Toepassingseigenschappen zijn door de gebruiker gedefinieerde tekenreeksen die kunnen worden toegevoegd aan het bericht. 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 eerst naar deze eigenschap in de systeemeigenschappen. Als deze niet wordt gevonden, wordt deze gezocht in de eigenschappen van de toepassing. In de volgende voorbeelden ziet u hoe u query's kunt uitvoeren op systeemeigenschappen en toepassingseigenschappen.

Query's uitvoeren op contentEncoding van de systeemeigenschap:

$contentEncoding = 'UTF-8'

Query's uitvoeren op het verwerkingspad van de toepassingseigenschap:

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 uitvoeren op basis van berichttekst

Als u query's wilt inschakelen 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 query-expressie niet in de berichttekst.

In het volgende JavaScript-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);
});

Zie de HubRoutingSample in de Microsoft Azure IoT SDK voor .NET voor een voorbeeld van een berichtcodering in C#. Dit voorbeeld is hetzelfde als in de zelfstudie Berichtroutering. Het Program.cs-bestand heeft ook een methode met de naam ReadOneRowFromFile, die een van de gecodeerde bestanden leest, codeert en schrijft het terug 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, 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. De volgende voorbeelden 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)

Query's uitvoeren op basis van apparaat of moduledubbel

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.

Dubbelquery-expressies

Een query op een apparaatdubbel of moduledubbel 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. 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 het gebruik twinvan , $twinof $bodybodyals eigenschapsnamen te vermijden. De volgende voorbeelden 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: ()<>@,;:\"/?={}.

Volgende stappen

Meer informatie over berichtroutering.
Probeer de zelfstudie voor berichtroutering.

Delen via