IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und NachrichtenroutingIoT Hub query language for device and module twins, jobs, and message routing

IoT Hub verfügt über eine leistungsstarke SQL-ähnliche Sprache zum Abrufen von Informationen zu Gerätezwillingen, Modulzwillingen, Aufträgen und zum Nachrichtenrouting.IoT Hub provides a powerful SQL-like language to retrieve information regarding device twins, module twins, jobs, and message routing. Dieser Artikel enthält Folgendes:This article presents:

  • Eine Einführung in die wichtigsten Features der IoT Hub-AbfragespracheAn introduction to the major features of the IoT Hub query language, and
  • Eine ausführliche Beschreibung der SpracheThe detailed description of the language. Weitere Informationen zur Abfragesprache für das Nachrichtenrouting finden Sie unter Abfragen im Nachrichtenrouting.For details on query language for message routing, see queries in message routing.

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.

Abfragen von Geräte- und ModulzwillingenDevice and module twin queries

Gerätezwillinge und Modulzwillinge können beliebige JSON-Objekte als Tags und Eigenschaften enthalten.Device twins and module twins can contain arbitrary JSON objects as both tags and properties. In IoT Hub können Sie Geräte- und Modulzwillinge als einzelnes JSON-Dokument abfragen, das alle Informationen zum Zwilling enthält.IoT Hub enables you to query device twins and module twins as a single JSON document containing all twin information.

Angenommen, Ihre IoT Hub-Gerätezwillinge weisen die folgende Struktur auf (Modulzwillinge sehen ähnlich aus, enthalten aber zusätzlich eine Modul-ID):Assume, for instance, that your IoT hub device twins have the following structure (module twin would be similar just with an additional moduleId):

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "Disconnected",
    "lastActivityTime": "0001-01-01T00:00:00",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "version": 2,
    "tags": {
        "location": {
            "region": "US",
            "plant": "Redmond43"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300
            },
            "$metadata": {
            ...
            },
            "$version": 4
        },
        "reported": {
            "connectivity": {
                "type": "cellular"
            },
            "telemetryConfig": {
                "configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
                "sendFrequencyInSecs": 300,
                "status": "Success"
            },
            "$metadata": {
            ...
            },
            "$version": 7
        }
    }
}

GerätezwillingabfragenDevice twin queries

IoT Hub macht die Gerätezwillinge als eine Dokumentensammlung namens Geräte verfügbar.IoT Hub exposes the device twins as a document collection called devices. Beispielsweise ruft die folgende Abfrage die gesamte Gruppe von Gerätezwillingen ab:For example, the following query retrieves the whole set of device twins:

SELECT * FROM devices

Hinweis

Azure IoT SDKs unterstützen die seitenweise Ausgabe von umfangreichen Ergebnissen.Azure IoT SDKs support paging of large results.

IoT Hub ermöglicht beim Abrufen von Gerätezwillingen das Filtern mit beliebigen Bedingungen.IoT Hub allows you to retrieve device twins filtering with arbitrary conditions. Verwenden Sie z. B. die folgende Abfrage, um Gerätezwillinge zu erhalten, bei denen das Tag location.region auf US festgelegt ist:For instance, to receive device twins where the location.region tag is set to US use the following query:

SELECT * FROM devices
WHERE tags.location.region = 'US'

Boolesche Operatoren und arithmetische Vergleiche werden ebenfalls unterstützt.Boolean operators and arithmetic comparisons are supported as well. Verwenden Sie z. B. die folgende Abfrage, um Gerätezwillinge in den USA abzurufen, die so konfiguriert sind, dass sie Telemetriedaten häufiger als jede Minute senden:For example, to retrieve device twins located in the US and configured to send telemetry less than every minute, use the following query:

SELECT * FROM devices
  WHERE tags.location.region = 'US'
    AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60

Zur Vereinfachung können auch Arraykonstanten mit den Operatoren IN und NIN (nicht IN) verwendet werden.As a convenience, it is also possible to use array constants with the IN and NIN (not in) operators. Verwenden Sie z. B. die folgende Abfrage, um Gerätezwillinge abzurufen, die WLAN- oder Kabelverbindungen melden:For instance, to retrieve device twins that report WiFi or wired connectivity use the following query:

SELECT * FROM devices
  WHERE properties.reported.connectivity IN ['wired', 'wifi']

Es ist häufig erforderlich, alle Gerätezwillinge zu ermitteln, die eine bestimmte Eigenschaft enthalten.It is often necessary to identify all device twins that contain a specific property. IoT Hub unterstützt zu diesem Zweck die Funktion is_defined().IoT Hub supports the function is_defined() for this purpose. Verwenden Sie z. B. die folgende Abfrage, um Gerätezwillinge abzurufen, die die connectivity-Eigenschaft definieren:For instance, to retrieve device twins that define the connectivity property use the following query:

SELECT * FROM devices
  WHERE is_defined(properties.reported.connectivity)

Die vollständige Referenz zu den Filtermöglichkeiten finden Sie im Abschnitt zur WHERE-Klausel.Refer to the WHERE clause section for the full reference of the filtering capabilities.

Gruppierungen und Aggregationen werden ebenfalls unterstützt.Grouping and aggregations are also supported. Verwenden Sie z. B. die folgende Abfrage, um die Anzahl von Geräten mit dem jeweiligen Status für die Telemetriekonfiguration zu ermitteln:For instance, to find the count of devices in each telemetry configuration status, use the following query:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
  FROM devices
  GROUP BY properties.reported.telemetryConfig.status

Diese Gruppierungsabfrage würde ein ähnliches Ergebnis wie im folgenden Beispiel zurückgegeben:This grouping query would return a result similar to the following example:

[
    {
        "numberOfDevices": 3,
        "status": "Success"
    },
    {
        "numberOfDevices": 2,
        "status": "Pending"
    },
    {
        "numberOfDevices": 1,
        "status": "Error"
    }
]

In diesem Beispiel meldeten drei Geräte eine erfolgreiche Konfiguration, zwei wenden die Konfiguration noch an und ein Gerät hat einen Fehler gemeldet.In this example, three devices reported successful configuration, two are still applying the configuration, and one reported an error.

Mithilfe von Projektionsabfragen können Entwickler nur die interessierenden Eigenschaften zurückgeben.Projection queries allow developers to return only the properties they care about. Um beispielsweise den Zeitpunkt der letzten Aktivität aller getrennten Geräte abzurufen, verwenden Sie die folgende Abfrage:For example, to retrieve the last activity time of all disconnected devices use the following query:

SELECT LastActivityTime FROM devices WHERE status = 'enabled'

ModulzwillingsabfragenModule twin queries

Das Abfragen von Modulzwillingen ähnelt dem Abfragen von Gerätezwillingen. Allerdings wird hierbei eine andere Sammlung bzw. ein anderer Namespace verwendet. Sie führen die Abfrage nicht über devices, sondern über device.modules durch:Querying on module twins is similar to querying on device twins, but using a different collection/namespace; instead of from devices, you query from devices.modules:

SELECT * FROM devices.modules

Eine Verknüpfung zwischen den Sammlungen „devices“ und „devices.modules“ ist nicht zulässig.We don't allow join between the devices and devices.modules collections. Wenn Sie Modulzwillinge geräteübergreifend abfragen möchten, müssen dazu Tags verwendet werden.If you want to query module twins across devices, you do it based on tags. Die folgende Abfrage gibt alle Modulzwillinge auf allen Geräten mit dem Status „scanning“ zurück:This query will return all module twins across all devices with the scanning status:

SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'

Die folgende Abfrage gibt alle Modulzwillinge mit dem Status „scanning“ nur für die angegebene Teilmenge der Geräte zurück:This query will return all module twins with the scanning status, but only on the specified subset of devices:

SELECT * FROM devices.modules
  WHERE properties.reported.status = 'scanning'
  AND deviceId IN ['device1', 'device2']

C#-BeispielC# example

Die Abfragefunktion wird durch das C#-Dienst-SDK in der RegistryManager-Klasse verfügbar gemacht.The query functionality is exposed by the C# service SDK in the RegistryManager class.

Es folgt ein Beispiel für eine einfache Abfrage:Here is an example of a simple query:

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

Das Objekt query wird mit einer Seitengröße (bis zu 100) instanziiert.The query object is instantiated with a page size (up to 100). Dann erfolgt der Abruf mehrerer Seiten, indem mehrmals die GetNextAsTwinAsync-Methoden aufgerufen werden.Then multiple pages are retrieved by calling the GetNextAsTwinAsync methods multiple times.

Das Abfrageobjekt macht mehrere Next-Werte verfügbar, abhängig von der Deserialisierungsoption, die von der Abfrage benötigt werden.The query object exposes multiple Next values, depending on the deserialization option required by the query. Beispielsweise Gerätezwillings- bzw. Auftragsobjekte oder einfachen JSON-Text bei der Verwendung von Projektionen.For example, device twin or job objects, or plain JSON when using projections.

Node.js-BeispielNode.js example

Die Abfragefunktion wird durch das Azure IoT-Dienst-SDK für Node.js im Registry-Objekt verfügbar gemacht.The query functionality is exposed by the Azure IoT service SDK for Node.js in the Registry object.

Es folgt ein Beispiel für eine einfache Abfrage:Here is an example of a simple query:

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

Das Objekt query wird mit einer Seitengröße (bis zu 100) instanziiert.The query object is instantiated with a page size (up to 100). Dann erfolgt der Abruf mehrerer Seiten, indem mehrmals die nextAsTwin-Methode aufgerufen wird.Then multiple pages are retrieved by calling the nextAsTwin method multiple times.

Das Abfrageobjekt macht mehrere Next-Werte verfügbar, abhängig von der Deserialisierungsoption, die von der Abfrage benötigt werden.The query object exposes multiple Next values, depending on the deserialization option required by the query. Beispielsweise Gerätezwillings- bzw. Auftragsobjekte oder einfachen JSON-Text bei der Verwendung von Projektionen.For example, device twin or job objects, or plain JSON when using projections.

EinschränkungenLimitations

Wichtig

Abfrageergebnisse können mit einigen Minuten Verzögerung im Vergleich zu den aktuellen Werten in Gerätezwillingen ausgegeben werden.Query results can have a few minutes of delay with respect to the latest values in device twins. Wenn Sie einzelne Gerätezwillinge nach ihrer ID abfragen, verwenden Sie die REST-API zum Abrufen von Gerätezwillingen.If querying individual device twins by ID, use the get twin REST API. Diese API gibt immer die aktuellen Werte zurück und weist höhere Einschränkungsgrenzwerte auf.This API always returns the latest values and has higher throttling limits. Sie können die REST-API direkt aufrufen oder die entsprechende Funktion in einem der Azure IoT Hub-Dienst-SDKs verwenden.You can issue the REST API directly or use the equivalent functionality in one of the Azure IoT Hub Service SDKs.

Derzeit werden Vergleiche nur zwischen primitiven Typen (keine Objekte) unterstützt. ... WHERE properties.desired.config = properties.reported.config wird beispielsweise nur unterstützt, wenn diese Eigenschaften über primitive Werte verfügen.Currently, comparisons are supported only between primitive types (no objects), for instance ... WHERE properties.desired.config = properties.reported.config is supported only if those properties have primitive values.

Erste Schritte mit AuftragsabfragenGet started with jobs queries

Aufträge bieten eine Möglichkeit zum Ausführen von Vorgängen für Gerätegruppen.Jobs provide a way to execute operations on sets of devices. Jeder Gerätezwilling enthält die Informationen der auf ihn bezogenen Aufträge in einer Sammlung namens jobs.Each device twin contains the information of the jobs of which it is part in a collection called jobs.

{
    "deviceId": "myDeviceId",
    "etag": "AAAAAAAAAAc=",
    "tags": {
        ...
    },
    "properties": {
        ...
    },
    "jobs": [
        {
            "deviceId": "myDeviceId",
            "jobId": "myJobId",
            "jobType": "scheduleTwinUpdate",
            "status": "completed",
            "startTimeUtc": "2016-09-29T18:18:52.7418462",
            "endTimeUtc": "2016-09-29T18:20:52.7418462",
            "createdDateTimeUtc": "2016-09-29T18:18:56.7787107Z",
            "lastUpdatedDateTimeUtc": "2016-09-29T18:18:56.8894408Z",
            "outcome": {
                "deviceMethodResponse": null
            }
        },
        ...
    ]
}

Diese Sammlung kann derzeit in der IoT Hub-Abfragesprache über devices.jobs abgefragt werden.Currently, this collection is queryable as devices.jobs in the IoT Hub query language.

Wichtig

Die „jobs“-Eigenschaft wird derzeit nie zurückgegeben, wenn Gerätezwillinge abgefragt werden.Currently, the jobs property is never returned when querying device twins. Hierbei handelt es sich um Abfragen, die „FROM devices“ enthalten.That is, queries that contain 'FROM devices'. Auf die „jobs“-Eigenschaft kann nur direkt mit Abfragen unter Verwendung von FROM devices.jobs zugegriffen werden.The jobs property can only be accessed directly with queries using FROM devices.jobs.

Um alle Aufträge (vergangene und geplante) abzurufen, die ein einzelnes Gerät betreffen, können Sie z.B. die folgende Abfrage verwenden:For instance, to get all jobs (past and scheduled) that affect a single device, you can use the following query:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'

Beachten Sie, wie diese Abfrage den gerätespezifischen Status (und möglicherweise die direkte Antwortmethode) jedes zurückgegebenen Auftrags bereitstellt.Note how this query provides the device-specific status (and possibly the direct method response) of each job returned.

Es ist auch möglich, mit beliebigen booleschen Bedingungen alle Objekteigenschaften in der Sammlung devices.jobs zu filtern.It is also possible to filter with arbitrary Boolean conditions on all object properties in the devices.jobs collection.

Verwenden Sie z. B. die folgende Abfrage, um alle abgeschlossenen Aktualisierungsaufträge von Gerätezwillingen abzurufen, die nach September 2016 für ein bestimmtes Gerät erstellt wurden:For instance, to retrieve all completed device twin update jobs that were created after September 2016 for a specific device, use the following query:

SELECT * FROM devices.jobs
  WHERE devices.jobs.deviceId = 'myDeviceId'
    AND devices.jobs.jobType = 'scheduleTwinUpdate'
    AND devices.jobs.status = 'completed'
    AND devices.jobs.createdTimeUtc > '2016-09-01'

Sie können auch die Ergebnisse pro Gerät eines einzelnen Auftrags abrufen.You can also retrieve the per-device outcomes of a single job.

SELECT * FROM devices.jobs
  WHERE devices.jobs.jobId = 'myJobId'

EinschränkungenLimitations

Derzeit wird für Abfragen von devices.jobs Folgendes nicht unterstützt:Currently, queries on devices.jobs do not support:

  • Projektionen, sodass nur SELECT * möglich ist.Projections, therefore only SELECT * is possible.
  • Bedingungen, die zusätzlich zu Auftragseigenschaften auf einen Gerätezwilling verweisen (siehe vorausgehender Abschnitt).Conditions that refer to the device twin in addition to job properties (see the preceding section).
  • Durchführung von Aggregationen, z.B. Zählen, Durchschnittsbildung, Gruppieren.Performing aggregations, such as count, avg, group by.

Grundlagen von IoT Hub-AbfragenBasics of an IoT Hub query

Jede IoT Hub-Abfrage besteht aus einer SELECT- und einer FROM-Klausel mit optionalen WHERE- und GROUP BY-Klauseln.Every IoT Hub query consists of SELECT and FROM clauses, with optional WHERE and GROUP BY clauses. Jede Abfrage wird für eine Sammlung von JSON-Dokumenten ausgeführt, z.B. Gerätezwillinge.Every query is run on a collection of JSON documents, for example device twins. Die FROM-Klausel zeigt die Dokumentsammlung an, die durchlaufen werden soll (devices, devices.modules oder devices.jobs).The FROM clause indicates the document collection to be iterated on (devices, devices.modules, or devices.jobs). Anschließend wird der Filter in der WHERE-Klausel angewendet.Then, the filter in the WHERE clause is applied. Mit Aggregationen werden die Ergebnisse dieses Schritts gruppiert, wie in der GROUP BY-Klausel angegeben.With aggregations, the results of this step are grouped as specified in the GROUP BY clause. Für jede Gruppe wird eine Zeile generiert, wie in der SELECT-Klausel angegeben.For each group, a row is generated as specified in the SELECT clause.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

Die FROM-KlauselFROM clause

Die Klausel FROM <from_specification> kann nur drei Werte haben: FROM devices, um Gerätezwillinge abzufragen, FROM devices.modules, um Modulzwillinge abzufragen, oder FROM devices.jobs, um Auftragsdetails pro Gerät abzufragen.The FROM <from_specification> clause can assume only three values: FROM devices to query device twins, FROM devices.modules to query module twins, or FROM devices.jobs to query job per-device details.

WHERE-KlauselWHERE clause

Die WHERE -Klausel ist optional.The WHERE <filter_condition> clause is optional. Sie gibt eine oder mehrere Bedingungen an, die von den in der FROM-Sammlung enthaltenen JSON-Dokumenten erfüllt werden müssen, um als Teil des Ergebnisses zurückgegeben zu werden.It specifies one or more conditions that the JSON documents in the FROM collection must satisfy to be included as part of the result. Jedes JSON-Dokument muss die angegebenen Bedingungen erfüllen, um in das Ergebnis einbezogen zu werden.Any JSON document must evaluate the specified conditions to "true" to be included in the result.

Die zulässigen Bedingungen werden im Abschnitt Ausdrücke und Bedingungen beschrieben.The allowed conditions are described in section Expressions and conditions.

Die SELECT-KlauselSELECT clause

Die SELECT -Klausel ist obligatorisch und gibt an, welche Werte von der Abfrage abgerufen werden.The SELECT <select_list> is mandatory and specifies what values are retrieved from the query. Sie gibt die JSON-Werte an, mit denen die neuen JSON-Objekte erstellt werden sollen.It specifies the JSON values to be used to generate new JSON objects. Für jedes Element der gefilterten (und optional gruppierten) Teilmenge der FROM-Sammlung wird in der Projektionsphase ein neues JSON-Objekt generiert.For each element of the filtered (and optionally grouped) subset of the FROM collection, the projection phase generates a new JSON object. Dieses Objekt wird mit den in der SELECT-Klausel angegebenen Werten erstellt.This object is constructed with the values specified in the SELECT clause.

Dies ist die Grammatik der SELECT-Klausel:Following is the grammar of the SELECT clause:

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name bezieht sich auf jede Eigenschaft des JSON-Dokuments in der FROM-Sammlung.Attribute_name refers to any property of the JSON document in the FROM collection. Im Abschnitt „Erste Schritte mit Gerätezwillingsabfragen“ finden Sie einige Beispiele für SELECT-Klauseln.Some examples of SELECT clauses can be found in the Getting started with device twin queries section.

Derzeit werden andere Auswahlklauseln als SELECT* nur in Aggregatabfragen für Gerätezwillinge unterstützt.Currently, selection clauses different than SELECT* are only supported in aggregate queries on device twins.

GROUP BY-KlauselGROUP BY clause

Die GROUP BY -Klausel ist ein optionaler Schritt, der nach dem in der WHERE-Klausel angegebenen Filter und vor der in der SELECT-Klausel angegebenen Projektion ausgeführt wird.The GROUP BY <group_specification> clause is an optional step that executes after the filter specified in the WHERE clause, and before the projection specified in the SELECT. Sie gruppiert Dokumente anhand des Werts eines Attributs.It groups documents based on the value of an attribute. Diese Gruppen werden verwendet, um aggregierte Werte gemäß der SELECT-Klausel zu generieren.These groups are used to generate aggregated values as specified in the SELECT clause.

Ein Beispiel für eine Abfrage mit GROUP BY:An example of a query using GROUP BY is:

SELECT properties.reported.telemetryConfig.status AS status,
    COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status

Die formale Syntax für GROUP BY lautet:The formal syntax for GROUP BY is:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name bezieht sich auf jede Eigenschaft des JSON-Dokuments in der FROM-Sammlung.Attribute_name refers to any property of the JSON document in the FROM collection.

Die GROUP BY-Klausel wird derzeit nur für Abfragen von Gerätezwillingen unterstützt.Currently, the GROUP BY clause is only supported when querying device twins.

Wichtig

Der Begriff group wird derzeit in Abfragen als spezielles Schlüsselwort behandelt.The term group is currently treated as a special keyword in queries. Wenn Sie group als Eigenschaftenname verwenden, sollten Sie ihn zur Vermeidung von Fehlern in doppelte Klammern einschließen, z.B. SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.In case, you use group as your property name, consider surrounding it with double brackets to avoid errors, e.g., SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.

Ausdrücke und BedingungenExpressions and conditions

Auf hoher Ebene wird ein Ausdruck:At a high level, an expression:

  • in eine Instanz eines JSON-Typs (z. B. boolescher Wert, Zahl, Zeichenfolge, Array oder Objekt) ausgewertet.Evaluates to an instance of a JSON type (such as Boolean, number, string, array, or object).
  • durch das Ändern von Daten aus dem JSON-Dokument des Geräts und Konstanten mit integrierten Operatoren und Funktionen definiert.Is defined by manipulating data coming from the device JSON document and constants using built-in operators and functions.

Bedingungen sind Ausdrücke, die als boolescher Wert ausgewertet werden.Conditions are expressions that evaluate to a Boolean. Jede Konstante, die sich vom booleschen Ausdruck true unterscheidet, wird als false betrachtet.Any constant different than Boolean true is considered as false. Diese Regel umfasst null, undefined, jede Objekt- oder Arrayinstanz, jede Zeichenfolge und den booleschen Ausdruck false.This rule includes null, undefined, any object or array instance, any string, and the Boolean false.

Die Syntax für Ausdrücke lautet:The syntax for expressions is:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

Informationen dazu, wofür die einzelnen Symbole in der Ausdruckssyntax stehen, finden Sie in der folgenden Tabelle:To understand what each symbol in the expressions syntax stands for, refer to the following table:

SymbolSymbol DefinitionDefinition
attribute_nameattribute_name Eine beliebige Eigenschaft des JSON-Dokuments in der FROM-Sammlung.Any property of the JSON document in the FROM collection.
binary_operatorbinary_operator Ein beliebiger binärer, im Abschnitt Operatoren aufgelisteter Operator.Any binary operator listed in the Operators section.
function_namefunction_name Eine beliebige im Abschnitt Funktionen aufgelistete Funktion.Any function listed in the Functions section.
decimal_literaldecimal_literal Ein Gleitkommawert, ausgedrückt in Dezimalschreibweise.A float expressed in decimal notation.
hexadecimal_literalhexadecimal_literal Eine Zahl, ausgedrückt durch die Zeichenfolge „0x“ gefolgt von einer Zeichenfolge von Hexadezimalzahlen.A number expressed by the string ‘0x’ followed by a string of hexadecimal digits.
string_literalstring_literal Zeichenfolgenliterale sind Unicode-Zeichenfolgen, die durch eine Sequenz aus null oder mehr Unicode-Zeichen oder Escapesequenzen dargestellt werden.String literals are Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. Zeichenfolgenliterale werden in einfache Anführungszeichen oder doppelte Anführungszeichen eingeschlossen.String literals are enclosed in single quotes or double quotes. Zulässige Escapezeichen: \', \", \\, \uXXXX für Unicode-Zeichen, die durch 4 Hexadezimalstellen definiert werden.Allowed escapes: \', \", \\, \uXXXX for Unicode characters defined by 4 hexadecimal digits.

OperatorenOperators

Die folgenden Operatoren werden unterstützt:The following operators are supported:

FamilieFamily OperatorenOperators
ArithmetikArithmetic +, -, *, /, %+, -, *, /, %
LogischLogical AND, OR, NOTAND, OR, NOT
VergleichComparison =, !=, <, >, <=, >=, <>=, !=, <, >, <=, >=, <>

FunctionsFunctions

Bei Abfragen von Zwillingen und Aufträgen wird nur folgende Funktion unterstützt:When querying twins and jobs the only supported function is:

FunktionFunction BeschreibungDescription
IS_DEFINED(Eigenschaft)IS_DEFINED(property) Gibt einen booleschen Wert zurück, um anzugeben, ob der Eigenschaft ein Wert zugewiesen wurde (inklusive null).Returns a Boolean indicating if the property has been assigned a value (including null).

In Routenbedingungen werden die folgenden mathematischen Funktionen unterstützt:In routes conditions, the following math functions are supported:

FunktionFunction BeschreibungDescription
ABS(x)ABS(x) Gibt den absoluten (positiven) Wert des angegebenen numerischen Ausdrucks zurück.Returns the absolute (positive) value of the specified numeric expression.
EXP(x)EXP(x) Gibt den Exponentialwert des angegebenen numerischen Ausdrucks (e^x) zurück.Returns the exponential value of the specified numeric expression (e^x).
POWER(x,y)POWER(x,y) Gibt den Wert des angegebenen Ausdrucks gemäß der angegebenen Potenz (x^y) zurück.Returns the value of the specified expression to the specified power (x^y).
SQUARE(x)SQUARE(x) Gibt die Quadratwurzel des angegebenen numerischen Werts zurück.Returns the square of the specified numeric value.
CEILING(x)CEILING(x) Gibt den kleinsten ganzzahligen Wert zurück, der größer oder gleich dem angegebenen numerischen Ausdruck ist.Returns the smallest integer value greater than, or equal to, the specified numeric expression.
FLOOR(x)FLOOR(x) Gibt die größte ganze Zahl zurück, die kleiner oder gleich dem angegebenen numerischen Ausdruck ist.Returns the largest integer less than or equal to the specified numeric expression.
SIGN(x)SIGN(x) Gibt das positive Vorzeichen (+1), null (0) oder das negative Vorzeichen (-1) des angegebenen numerischen Ausdrucks zurück.Returns the positive (+1), zero (0), or negative (-1) sign of the specified numeric expression.
SQRT(x)SQRT(x) Gibt die Quadratwurzel des angegebenen numerischen Werts zurück.Returns the square root of the specified numeric value.

In Routenbedingungen werden die folgenden Typüberprüfungs- und Umwandlungsfunktionen unterstützt:In routes conditions, the following type checking and casting functions are supported:

FunktionFunction BeschreibungDescription
AS_NUMBERAS_NUMBER Konvertiert die Eingabezeichenfolge in eine Zahl.Converts the input string to a number. noop, wenn die Eingabe eine Zahl ist; Undefined, wenn die Zeichenfolge keine Zahl darstellt.noop if input is a number; Undefined if string does not represent a number.
IS_ARRAYIS_ARRAY Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Array“ ist.Returns a Boolean value indicating if the type of the specified expression is an array.
IS_BOOLIS_BOOL Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „boolesch“ ist.Returns a Boolean value indicating if the type of the specified expression is a Boolean.
IS_DEFINEDIS_DEFINED Gibt einen booleschen Wert zurück, um anzugeben, ob der Eigenschaft ein Wert zugewiesen wurde.Returns a Boolean indicating if the property has been assigned a value.
IS_NULLIS_NULL Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „NULL“ ist.Returns a Boolean value indicating if the type of the specified expression is null.
IS_NUMBERIS_NUMBER Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Zahl“ ist.Returns a Boolean value indicating if the type of the specified expression is a number.
IS_OBJECTIS_OBJECT Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „JSON-Objekt“ ist.Returns a Boolean value indicating if the type of the specified expression is a JSON object.
IS_PRIMITIVEIS_PRIMITIVE Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck ein Grundtyp ist (Zeichenfolge, boolesch, numerisch oder null).Returns a Boolean value indicating if the type of the specified expression is a primitive (string, Boolean, numeric, or null).
IS_STRINGIS_STRING Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Zeichenfolge“ ist.Returns a Boolean value indicating if the type of the specified expression is a string.

In Routenbedingungen werden die folgenden Zeichenfolgenfunktionen unterstützt:In routes conditions, the following string functions are supported:

FunktionFunction BeschreibungDescription
CONCAT(x, y, …)CONCAT(x, y, …) Gibt eine Zeichenfolge zurück, die das Ergebnis der Verkettung von zwei oder mehr Zeichenfolgenwerten darstellt.Returns a string that is the result of concatenating two or more string values.
LENGTH(x)LENGTH(x) Gibt die Anzahl der Zeichen im angegebenen Zeichenfolgenausdruck zurück.Returns the number of characters of the specified string expression.
LOWER(x)LOWER(x) Gibt eine Zeichenfolge zurück, nachdem Großbuchstaben in Kleinbuchstaben konvertiert wurden.Returns a string expression after converting uppercase character data to lowercase.
UPPER(x)UPPER(x) Gibt eine Zeichenfolge zurück, nachdem Kleinbuchstaben in Großbuchstaben konvertiert wurden.Returns a string expression after converting lowercase character data to uppercase.
SUBSTRING(Zeichenfolge, Start [, Länge])SUBSTRING(string, start [, length]) Gibt einen Teil eines Zeichenfolgenausdrucks zurück. Das angegebene Zeichen ist der Nullpunkt, von dem ab die Teilzeichenfolge in angegebener Länge bzw. bis zum Ende der Zeichenfolge zurückgegeben wird.Returns part of a string expression starting at the specified character zero-based position and continues to the specified length, or to the end of the string.
INDEX_OF(Zeichenfolge, Fragment)INDEX_OF(string, fragment) Gibt die Anfangsposition des ersten Vorkommens des zweiten Zeichenfolgenausdrucks innerhalb des ersten angegebenen Zeichenfolgenausdrucks zurück, oder -1, wenn die Zeichenfolge nicht gefunden wird.Returns the starting position of the first occurrence of the second string expression within the first specified string expression, or -1 if the string is not found.
STARTS_WITH(x, y)STARTS_WITH(x, y) Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck mit dem zweiten beginnt.Returns a Boolean indicating whether the first string expression starts with the second.
ENDS_WITH(x, y)ENDS_WITH(x, y) Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck mit dem zweiten endet.Returns a Boolean indicating whether the first string expression ends with the second.
CONTAINS(x,y)CONTAINS(x,y) Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck den zweiten enthält.Returns a Boolean indicating whether the first string expression contains the second.

Nächste SchritteNext steps

Informieren Sie sich darüber, wie Sie Abfragen in Ihren Apps mit Azure IoT SDKs ausführen.Learn how to execute queries in your apps using Azure IoT SDKs.