Abfragesyntax für das IoT Hub-Nachrichtenrouting

Das Nachrichtenrouting ermöglicht es Benutzern, unterschiedliche Datentypen – nämlich 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“ finden Sie unter Wählen des passenden 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 Text nicht das JSON-Format aufweist, kann die Nachricht dennoch durch das Nachrichtenrouting weitergeleitet werden, jedoch können keine Abfragen des Nachrichtentexts ausgeführt werden. Abfragen werden als „boolesche Ausdrücke“ beschrieben. Hierbei sorgt der boolesche Wert „true“ dafür, dass die Abfrage erfolgreich ist und alle eingehenden Daten weiterleitet. Der boolesche Wert „false“ sorgt dafür, dass die Abfrage fehlschlägt und Daten nicht weitergeleitet werden. Wenn die Auswertung des Ausdrucks „null“ oder „nicht definiert“ ergibt, wird er als „false“ behandelt. Außerdem wird in den IoT Hub-Ressourcenprotokollen zu Routen eine Fehlermeldung generiert. Damit die Weiterleitung gespeichert und ausgewertet wird, muss die Abfragesyntax richtig sein.

Abfrage des Nachrichtenroutings 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 das Gerät-zu-Cloud-Messaging von IoT Hub die Groß-/Kleinschreibung nicht beachtet. 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

Mithilfe von Systemeigenschaften kann der Inhalt und die Quelle der Nachrichten identifiziert werden.

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 „contentType“ auf „application/JSON“ festgelegt wird, sind UTF-8, UTF-16 oder UTF-32 zulässige Werte.
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.

Wie in Erstellen und Lesen von IoT Hub-Nachrichten beschrieben, gibt es in einer Nachricht zusätzliche Systemeigenschaften. Zusätzlich zu den Eigenschaften in der obigen Tabelle können Sie auch connectionDeviceId und connectionModuleId abfragen.

Anwendungseigenschaften

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

Abfrageausdrücke

Abfragen der Nachrichtensystemeigenschaften muss das Symbol $ vorangestellt werden. Auf Abfragen von Anwendungseigenschaften wird anhand der Namen zugegriffen, ihnen sollte das Symbol $ nicht vorangestellt werden. Wenn der Name einer Anwendungseigenschaft mit $ beginnt, sucht IoT Hub zunächst in den Systemeigenschaften nach dieser. Wenn sie dort nicht gefunden werden konnte, wird in den Anwendungseigenschaften gesucht. Beispiel:

So führen Sie eine Abfrage der Systemeigenschaft „contentEncoding“ durch

$contentEncoding = 'UTF-8'

So führen Sie eine Abfrage der Anwendungseigenschaft „processingPath“ 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 unter Ausdrücke und Bedingungen.

Abfrage des Nachrichtenroutings basierend auf dem Nachrichtentext

Die Nachricht sollte ein mit UTF-8, UTF-16 oder UTF-32 codiertes JSON-Format aufweisen, um das Abfragen des Nachrichtentexts zu ermöglichen. contentType muss auf application/JSON und contentEncoding muss in der Systemeigenschaft auf eine der unterstützten UTF-Codierungen festgelegt sein. Wenn diese Eigenschaften nicht festgelegt sind, wird der Abfrageausdruck für den Nachrichtentext nicht von IoT Hub ausgewertet.

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

Hinweis

Hier sehen Sie, wie die Codierung des Texts in JavaScript behandelt werden muss. Wenn Sie sich ein Beispiel in C# ansehen möchten, laden Sie das Azure IoT C#-SDK herunter. Entzippen Sie die Datei „master.zip“. In der Datei „Program.cs“ aus der Visual Studio-Projektmappe SimulatedDevice werden die Codierung und Übermittlung von Nachrichten an eine IoT Hub-Instanz gezeigt. Dieses Beispiel wird auch im Nachrichtenrouting-Tutorial zum Testen des Nachrichtenroutings verwendet. Am Ende von „Program.cs“ befindet sich auch eine Methode, die dazu dient, in einer der codierten Dateien zu lesen, die Datei zu decodieren und den Inhalt als lesbaren ASCII-Code auszugeben.

Abfrageausdrücke

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 Nachrichtensystemeigenschaften und einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren. Die folgenden Abfrageausdrücke sind beispielsweise sämtlich gültig:

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

Hinweis

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 danach, wann eine gewünschte Eigenschaft in sendFrequency geändert wurde 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)

Hinweis

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. Beispielsweise wird die folgende Abfrage nicht unterstützt und gibt undefined zurück:

$body[0] = 'Feb'

Abfrage des Nachrichtenroutings basierend auf dem Gerätezwilling

Das Nachrichtenrouting ermöglicht Ihnen das Abfragen von Tags und Eigenschaften des Gerätezwillings, die JSON-Objekte sind. Das Abfragen des Modulzwillings wird ebenfalls unterstützt. Im Folgenden wird ein Beispiel für Gerätezwillingstags gezeigt.

{
    "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. aus IoT Edge-Modulen), fragen den Modulzwilling und nicht den zugehörigen Gerätezwilling ab.

Abfrageausdrücke

Einer Abfrage auf einem Geräte- oder Modulzwilling muss das Präfix $twin vorangestellt werden. Der Abfrageausdruck kann auch ein Zwillingstag oder Eigenschaftenverweis mit einem Textverweis, einem Verweis auf Nachrichtensystemeigenschaften und/oder einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren. Die Verwendung eindeutiger Namen wird für Tags und Eigenschaften empfohlen, da die Abfrage die Groß- und Kleinschreibung nicht beachtet. Dies gilt für Gerätezwillinge und Modulzwillinge. Außerdem sollten Sie twin, $twin, body oder $body nicht als Eigenschaftennamen verwenden. Die folgenden Abfrageausdrücke sind beispielsweise sämtlich gültig:

$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