Abfragesyntax für das IoT Hub-NachrichtenroutingIoT Hub message routing query syntax

Das Nachrichtenrouting ermöglicht Benutzern, verschiedene Datentypen wie Gerätetelemetrienachrichten, Gerätelebenszyklusereignisse und Änderungsereignisse für Gerätezwillinge an verschiedene Endpunkte weiterzuleiten.Message routing enables users to route different data types namely, device telemetry messages, device lifecycle events, and device twin change events to various endpoints. 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.You can also apply rich queries to this data before routing it to receive the data that matters to you. In diesem Artikel werden die Abfragesprache für das IoT Hub-Nachrichtenrouting beschrieben und allgemeine Abfragemuster bereitgestellt.This article describes the IoT Hub message routing query language, and provides some common query patterns.

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.Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. 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.For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

Mithilfe des Nachrichtenroutings können Sie Abfragen für Nachrichteneigenschaften und Nachrichtentext sowie für Gerätezwillingstags und Gerätezwillingseigenschaften durchführen.Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. 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.If the message body is not JSON, message routing can still route the message, but queries cannot be applied to the message body. Abfragen werden mit booleschen Ausdrücken beschrieben. Hierbei gibt der boolesche Wert TRUE an, dass die Abfrage erfolgreich ist, wodurch alle eingehenden Daten weitergeleitet werden, und der boolesche Wert FALSE gibt an, dass die Abfrage fehlgeschlagen ist und Daten nicht weitergeleitet werden.Queries are described as Boolean expressions where a Boolean true makes the query succeed which routes all the incoming data, and Boolean false fails the query and no data is routed. Wenn die Auswertung des Ausdrucks NULL oder „nicht definiert“ ergibt, wird er als FALSE angesehen. Außerdem wird im Fall eines Fehlers eine Fehlermeldung in den Protokollen zu Routenressourcen von IoT Hub generiert.If the expression evaluates to null or undefined, it is treated as false and an error will be generated in IoT Hub routes resource logs logs in case of a failure. Damit die Weiterleitung gespeichert und ausgewertet wird, muss die Abfragesyntax richtig sein.The query syntax must be correct for the route to be saved and evaluated.

Abfrage des Nachrichtenroutings basierend auf NachrichteneigenschaftenMessage routing query based on message properties

Der IoT Hub definiert ein gemeinsames Format für alle Gerät-zu-Cloud-Nachrichten, um Interoperabilität zwischen Protokollen zu ermöglichen.The IoT Hub defines a common format for all device-to-cloud messaging for interoperability across protocols. Die IoT Hub-Nachricht geht von der folgenden JSON-Darstellung der Nachricht aus.IoT Hub message assumes the following JSON representation of the message. Systemeigenschaften identifizieren den Nachrichteninhalt und werden allen Benutzern hinzugefügt.System properties are added for all users and identify content of the message. Benutzer können der Nachricht selektiv Anwendungseigenschaften hinzufügen.Users can selectively add application properties to the message. Die Verwendung eindeutiger Eigenschaftennamen wird empfohlen, da das Gerät-zu-Cloud-Messaging von IoT Hub die Groß-/Kleinschreibung nicht beachtet.We recommend using unique property names as IoT Hub device-to-cloud messaging is not case-sensitive. Wenn Sie beispielsweise über mehrere Eigenschaften mit dem gleichen Namen verfügen, sendet IoT Hub nur eine der Eigenschaften.For example, if you have multiple properties with the same name, IoT Hub will only send one of the properties.

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

SystemeigenschaftenSystem properties

Mithilfe von Systemeigenschaften werden Inhalt und Quelle von Nachrichten identifiziert.System properties help identify contents and source of the messages.

EigenschaftProperty typeType BESCHREIBUNGDescription
contentTypecontentType stringstring Der Benutzer gibt den Inhaltstyp der Nachricht an.The user specifies the content type of the message. Dieser Wert sollte auf „application/JSON“ festgelegt werden, damit Abfragen für den Nachrichtentext ausgeführt werden können.To allow query on the message body, this value should be set application/JSON.
contentEncodingcontentEncoding stringstring Der Benutzer gibt den Codierungstyp der Nachricht an.The user specifies the encoding type of the message. Wenn contentType auf „application/JSON“ festgelegt ist, sind die folgenden Werte gültig: UTF-8, UTF-16 und UTF-32.Allowed values are UTF-8, UTF-16, UTF-32 if the contentType is set to application/JSON.
iothub-connection-device-idiothub-connection-device-id stringstring Dieser Wert wird von IoT Hub festgelegt, und er identifiziert die ID des Geräts.This value is set by IoT Hub and identifies the ID of the device. Verwenden Sie $connectionDeviceId für die Abfrage.To query, use $connectionDeviceId.
iothub-enqueuedtimeiothub-enqueuedtime stringstring Dieser Wert wird von IoT Hub festgelegt und stellt den tatsächlichen Zeitpunkt dar, zu dem die Nachricht in UTC eingereiht wird.This value is set by IoT Hub and represents the actual time of enqueuing the message in UTC. Verwenden Sie enqueuedTime für die Abfrage.To query, use enqueuedTime.
dt-dataschemadt-dataschema stringstring Dieser Wert wird von IoT Hub für Gerät-zu-Cloud-Nachrichten festgelegt.This value is set by IoT hub on device-to-cloud messages. Er enthält die in der Geräteverbindung festgelegte Gerätemodell-ID.It contains the device model ID set in the device connection. Verwenden Sie $dt-dataschema für die Abfrage.To query, use $dt-dataschema.
dt-subjectdt-subject Zeichenfolgestring Der Name der Komponente, die die Gerät-zu-Cloud-Nachrichten sendet.The name of the component that is sending the device-to-cloud messages. Verwenden Sie $dt-subject für die Abfrage.To query, use $dt-subject.

Wie im Artikel zu IoT Hub-Nachrichten beschrieben wird, gibt es mehrere zusätzliche Systemeigenschaften in einer Nachricht.As described in the IoT Hub Messages, there are additional system properties in a message. Zusätzlich zu den Eigenschaften in der obigen Tabelle können Sie auch connectionDeviceId und connectionModuleId abfragen.In addition to above properties in the previous table, you can also query connectionDeviceId, connectionModuleId.

AnwendungseigenschaftenApplication properties

Anwendungseigenschaften sind benutzerdefinierte Zeichenfolgen, die der Nachricht hinzugefügt werden können.Application properties are user-defined strings that can be added to the message. Diese Felder sind optional.These fields are optional.

AbfrageausdrückeQuery expressions

Abfragen der Nachrichtensystemeigenschaften muss das Symbol $ vorangestellt werden.A query on message system properties needs to be prefixed with the $ symbol. Auf Abfragen von Anwendungseigenschaften wird anhand der Namen zugegriffen, ihnen sollte das Symbol $ nicht vorangestellt werden.Queries on application properties are accessed with their name and should not be prefixed with the $symbol. 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.If an application property name begins with $, then IoT Hub will search for it in the system properties, and it is not found, then it will look in the application properties. Beispiel:For example:

So führen Sie eine Abfrage der Systemeigenschaft „contentEncoding“ durchTo query on system property contentEncoding

$contentEncoding = 'UTF-8'

So führen Sie eine Abfrage der Anwendungseigenschaft „processingPath“ durchTo query on application property processingPath:

processingPath = 'hot'

Sie können boolesche Ausdrücke und Funktionen verwenden, um diese Abfragen zu kombinieren:To combine these queries, you can use Boolean expressions and functions:

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

Eine vollständige Liste der unterstützten Operatoren und Funktionen finden Sie unter Ausdrücke und Bedingungen.A full list of supported operators and functions is shown in Expression and conditions.

Abfrage des Nachrichtenroutings basierend auf dem NachrichtentextMessage routing query based on message body

Die Nachricht sollte ein mit UTF-8, UTF-16 oder UTF-32 codiertes JSON-Format aufweisen, um das Abfragen des Nachrichtentexts zu ermöglichen.To enable querying on message body, the message should be in a JSON encoded in either UTF-8, UTF-16 or UTF-32. contentType muss auf application/JSON und contentEncoding muss in der Systemeigenschaft auf eine der unterstützten UTF-Codierungen festgelegt sein.The contentType must be set to application/JSON and contentEncoding to one of the supported UTF encodings in the system property. Wenn diese Eigenschaften nicht festgelegt sind, wird der Abfrageausdruck für den Nachrichtentext nicht von IoT Hub ausgewertet.If these properties are not specified, IoT Hub will not evaluate the query expression on the message body.

Das folgende Beispiel zeigt, wie eine Nachricht mit einem ordnungsgemäß formatierten und codierten JSON-Text erstellt wird:The following example shows how to create a message with a properly formed and encoded JSON body:

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.This shows how to handle the encoding of the body in javascript. Wenn Sie sich ein Beispiel in C# ansehen möchten, laden Sie die Azure IoT-Beispiele für C# herunter.If you want to see a sample in C#, download the Azure IoT C# Samples. Entzippen Sie die Datei „master.zip“.Unzip the master.zip file. In der Datei „Program.cs“ aus der Visual Studio-Projektmappe SimulatedDevice werden die Codierung und Übermittlung von Nachrichten an eine IoT Hub-Instanz gezeigt.The Visual Studio solution SimulatedDevice's Program.cs file shows how to encode and submit messages to an IoT Hub. Dieses Beispiel wird auch im Nachrichtenrouting-Tutorial zum Testen des Nachrichtenroutings verwendet.This is the same sample used for testing the message routing, as explained in the Message Routing tutorial. 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.At the bottom of Program.cs, it also has a method to read in one of the encoded files, decode it, and write it back out as ASCII so you can read it.

AbfrageausdrückeQuery expressions

Einer Abfrage des Nachrichtentexts muss das Präfix $body vorangestellt werden.A query on message body needs to be prefixed with the $body. Sie können einen Textverweis, Textarrayverweis oder mehrere Textverweise im Abfrageausdruck verwenden.You can use a body reference, body array reference, or multiple body references in the query expression. Der Abfrageausdruck kann auch einen Textverweis mit Nachrichtensystemeigenschaften und einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren.Your query expression can also combine a body reference with message system properties, and message application properties reference. Die folgenden Abfrageausdrücke sind beispielsweise sämtlich gültig:For example, the following are all valid query expressions:

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

Abfrage des Nachrichtenroutings basierend auf dem GerätezwillingMessage routing query based on device twin

Das Nachrichtenrouting ermöglicht Ihnen das Abfragen von Tags und Eigenschaften des Gerätezwillings, die JSON-Objekte sind.Message routing enables you to query on Device Twin tags and properties, which are JSON objects. Das Abfragen des Modulzwillings wird ebenfalls unterstützt.Querying on module twin is also supported. Im Folgenden wird ein Beispiel für Gerätezwillingstags gezeigt.A sample of Device Twin tags and properties is shown below.

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

AbfrageausdrückeQuery expressions

Einer Abfrage des Nachrichtenzwillings muss das Präfix $twin vorangestellt werden.A query on message twin needs to be prefixed with the $twin. Der Abfrageausdruck kann auch ein Zwillingstag oder Eigenschaftenverweis mit einem Textverweis und mit Nachrichtensystemeigenschaften sowie einem Verweis auf Nachrichtenanwendungseigenschaften kombinieren.Your query expression can also combine a twin tag or property reference with a body reference, message system properties, and message application properties reference. Die Verwendung eindeutiger Namen wird für Tags und Eigenschaften empfohlen, da die Abfrage die Groß- und Kleinschreibung nicht beachtet.We recommend using unique names in tags and properties as the query is not case-sensitive. Dies gilt für Gerätezwillinge und Modulzwillinge.This applies to both device twins and module twins. Außerdem sollten Sie twin, $twin, body oder $body nicht als Eigenschaftennamen verwenden.Also refrain from using twin, $twin, body, or $body, as a property names. Die folgenden Abfrageausdrücke sind beispielsweise sämtlich gültig:For example, the following are all valid query expressions:

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

Routingabfragen für Text oder Gerätezwilling mit einem Punkt in der Nutzlast oder im Eigenschaftsnamen werden nicht unterstützt.Routing query on body or device twin with a period in the payload or property name is not supported.

Nächste SchritteNext steps