Abfragesyntax für das IoT Hub-Nachrichtenrouting

Artikel
03/18/2023

Das Nachrichtenrouting ermöglicht es Benutzern, verschiedene Datentypen (einschließlich Gerätetelemetrienachrichten, Gerätelebenszyklusereignisse und Änderungsereignisse für Gerätezwillinge) an verschiedene Endpunkte weiterzuleiten. Sie können auch umfassende Abfragen für diese Daten ausführen, bevor Sie sie weiterleiten, um die Daten zu empfangen, die für Sie wichtig sind. In diesem Artikel werden die Abfragesprache für das IoT Hub-Nachrichtenrouting beschrieben und allgemeine Abfragemuster bereitgestellt.

Hinweis

Einige der in diesem Artikel erwähnten Features (wie Cloud-zu-Gerät-Messaging, Gerätezwillinge und Geräteverwaltung) stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Mithilfe des Nachrichtenroutings können Sie Abfragen für Nachrichteneigenschaften und Nachrichtentext sowie für Gerätezwillingstags und Gerätezwillingseigenschaften durchführen. Wenn der Nachrichtentext nicht im JSON-Format vorliegt, kann das Nachrichtenrouting die Nachricht trotzdem routen, es können jedoch keine Abfragen auf den Nachrichtentext angewendet werden. Abfragen werden als boolesche Ausdrücke beschrieben. Bei „true“ wird die Abfrage erfolgreich ausgeführt, und alle eingehenden Daten werden weitergeleitet. Andernfalls schlägt die Abfrage fehl, und die eingehenden Daten werden nicht weitergeleitet. Wenn der Ausdruck zu einem Wert „NULL“ oder „nicht definiert“ ausgewertet wird, wird er als boolescher Wert FALSCH behandelt und generiert einen Fehler in den Ressourcenprotokollen zu Routen von IoT Hub. Damit die Weiterleitung gespeichert und ausgewertet wird, muss die Abfragesyntax richtig sein.

Abfrage basierend auf Nachrichteneigenschaften

IoT Hub definiert ein gemeinsames Format für alle Gerät-zu-Cloud-Nachrichten, um Interoperabilität zwischen Protokollen zu ermöglichen. IoT Hub geht von der folgenden JSON-Darstellung der Nachricht aus. Systemeigenschaften identifizieren den Nachrichteninhalt und werden allen Benutzern hinzugefügt. Benutzer können der Nachricht selektiv Anwendungseigenschaften hinzufügen. Die Verwendung eindeutiger Eigenschaftennamen wird empfohlen, da beim Gerät-zu-Cloud-Messaging von IoT Hub die Groß-/Kleinschreibung nicht beachtet wird. Wenn Sie beispielsweise über mehrere Eigenschaften mit dem gleichen Namen verfügen, sendet IoT Hub nur eine der Eigenschaften.

{ 
  "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}}" 
  } 
}

Systemeigenschaften

Systemeigenschaften helfen beim Identifizieren der Inhalte und der Quelle der Nachrichten. Einige dieser Eigenschaften sind in der folgenden Tabelle beschrieben:

Eigenschaft	type	BESCHREIBUNG
contentType	string	Der Benutzer gibt den Inhaltstyp der Nachricht an. Dieser Wert sollte auf `application/JSON` festgelegt werden, damit Abfragen für den Nachrichtentext ausgeführt werden können.
contentEncoding	string	Der Benutzer gibt den Codierungstyp der Nachricht an. Wenn die Eigenschaft „contentType“ auf `application/JSON` festgelegt ist, dann sind die erlaubten Werte `UTF-8`, `UTF-16` und `UTF-32`.
iothub-connection-device-id	string	Dieser Wert wird von IoT Hub festgelegt, und er identifiziert die ID des Geräts. Verwenden Sie `$connectionDeviceId` für die Abfrage.
iothub-connection-module-id	Zeichenfolge	Dieser Wert wird von IoT Hub festgelegt und dient der Identifikation der Edge-Modul-ID. Verwenden Sie `$connectionModuleId` für die Abfrage.
iothub-enqueuedtime	string	Dieser Wert wird von IoT Hub festgelegt und stellt den tatsächlichen Zeitpunkt dar, zu dem die Nachricht in UTC eingereiht wird. Verwenden Sie `$enqueuedTime` für die Abfrage.
dt-dataschema	string	Dieser Wert wird von IoT Hub für Gerät-zu-Cloud-Nachrichten festgelegt. Er enthält die in der Geräteverbindung festgelegte Gerätemodell-ID. Verwenden Sie `$dt-dataschema` für die Abfrage.
dt-subject	Zeichenfolge	Der Name der Komponente, die die Gerät-zu-Cloud-Nachrichten sendet. Verwenden Sie `$dt-subject` für die Abfrage.

Weitere Informationen zu den anderen verfügbaren Systemeigenschaften finden Sie unter Erstellen und Lesen von IoT Hub-Nachrichten.

Anwendungseigenschaften

Anwendungseigenschaften sind benutzerdefinierte Zeichenfolgen, die der Nachricht hinzugefügt werden können. Diese Felder sind optional.

Abfrageausdrücke für Nachrichteneigenschaften

Abfragen der Nachrichtensystemeigenschaften muss das Symbol $ vorangestellt werden. Auf Abfragen von Anwendungseigenschaften wird anhand der Namen zugegriffen. Diesen Abfragen sollte das Symbol $ nicht vorangestellt werden. Wenn der Name einer Anwendungseigenschaft mit $ beginnt, sucht IoT Hub zunächst in den Systemeigenschaften nach dieser Eigenschaft. Wenn sie dort nicht gefunden wird, werden die Anwendungseigenschaften durchsucht. In den folgenden Beispielen wird gezeigt, wie Sie System- und Anwendungseigenschaften abfragen.

So führen Sie eine Abfrage der contentEncoding-Systemeigenschaft durch:

$contentEncoding = 'UTF-8'

So führen Sie eine Abfrage der processingPath-Anwendungseigenschaft durch:

processingPath = 'hot'

Sie können boolesche Ausdrücke und Funktionen verwenden, um diese Abfragen zu kombinieren:

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

Eine vollständige Liste der unterstützten Operatoren und Funktionen finden Sie im Abschnitt Ausdrücke und Bedingungen in IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenrouting.

Abfrage basierend auf Nachrichtentext

Die Nachricht sollte ein JSON-Format aufweisen und mit UTF-8, UTF-16 oder UTF-32 codiert sein, um das Abfragen des Nachrichtentexts zu ermöglichen. Die contentType-Systemeigenschaft muss application/JSON sein. Die contentEncoding-Systemeigenschaft muss einer der UTF-Codierungswerte sein, die von dieser Systemeigenschaft unterstützt werden. Wenn diese Systemeigenschaften nicht festgelegt sind, wird der Abfrageausdruck für den Nachrichtentext nicht von IoT Hub ausgewertet.

Das folgende JavaScript-Beispiel zeigt, wie eine Nachricht mit einem ordnungsgemäß formatierten und codierten JSON-Text erstellt wird:

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);
});

Ein Beispiel für die Nachrichtencodierung in C# finden Sie unter HubRoutingSample im Microsoft Azure IoT-SDK für .NET. Dieses Beispiel ist das gleiche wie im Tutorial zum Nachrichtenrouting. Die Datei „Program.cs“ verfügt auch über eine Methode namens ReadOneRowFromFile, die eine der codierten Dateien liest, diese decodiert und als ASCII-Code zurückschreibt, damit Sie sie lesen können.

Abfrageausdrücke für Nachrichtentext

Einer Abfrage des Nachrichtentexts muss das Präfix $body vorangestellt werden. Sie können einen Textverweis, Textarrayverweis oder mehrere Textverweise im Abfrageausdruck verwenden. Der Abfrageausdruck kann auch einen Textverweis mit einem Verweis auf Nachrichtensystemeigenschaften oder einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren. Die folgenden Beispiele sind z. B. alle gültige Abfrageausdrücke:

$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'

Abfragen und Funktionen können nur für Eigenschaften im Textverweis ausgeführt werden. Sie können keine Abfragen oder Funktionen für den gesamten Textverweis ausführen. Die folgende Abfrage wird beispielsweise nicht unterstützt und gibt undefined zurück:

$body[0] = 'Feb'

Um die Payload durch Zwillingsbenachrichtigungen basierend auf den Änderungen zu filtern, führen Sie Ihre Abfrage für den Nachrichtentext aus. So filtern Sie beispielsweise, wenn es eine gewünschte Eigenschaftsänderung an sendFrequency gibt und der Wert größer als 10 ist:

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

Zum Filtern von Nachrichten, die eine Eigenschaftsänderung enthalten, die unabhängig vom Wert der Eigenschaft ist, können Sie die is_defined()-Funktion verwenden (wenn der Wert ein primitiver Typ ist):

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

Abfrage basierend auf dem Gerät oder dem Modulzwilling

Das Nachrichtenrouting ermöglicht Ihnen das Abfragen von Tags und Eigenschaften des Gerätezwillings oder des Modulzwillings, welche JSON-Objekte sind. Das folgende Beispiel zeigt einen Gerätezwilling mit Tags und Eigenschaften:

{
    "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 
        } 
    } 
}

Hinweis

Module erben keine Zwillingstags von ihren zugehörigen Geräten. Zwillingsabfragen für Nachrichten, die von Gerätemodulen stammen (z. B. IoT Edge-Module), fragen den Modulzwilling und nicht den zugehörigen Gerätezwilling ab.

Zwillingsabfrageausdrücke

Einer Abfrage für einen Geräte- oder Modulzwilling muss das Präfix $twin vorangestellt werden. Der Abfrageausdruck kann auch ein Zwillingstag oder einen Eigenschaftenverweis mit einem Textverweis, einem Verweis auf Nachrichtensystemeigenschaften oder einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren. Die Verwendung eindeutiger Namen in Tags und Eigenschaften wird empfohlen, da die Abfrage die Groß-/Kleinschreibung nicht beachtet. Diese Empfehlung gilt für Gerätezwillinge und Modulzwillinge. Es wird auch empfohlen, die Verwendung von twin, $twin, body oder $body als Eigenschaftennamen zu vermeiden. Die folgenden Beispiele sind z. B. alle gültige Abfrageausdrücke:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Einschränkungen

Routingabfragen unterstützen nicht die Verwendung von Leerzeichen oder eines der folgenden Zeichen in Eigenschaftennamen, im Nachrichtentextpfad oder im Gerät/Modul-Twin-Pfad: ()<>@,;:\"/?={}.

Nächste Schritte

Erfahren Sie mehr über das Nachrichtenrouting.
Sehen Sie sich das Tutorial zum Nachrichtenrouting an.