Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
IoT Hub verfügt über eine leistungsstarke SQL-ähnliche Sprache zum Abrufen von Informationen zu Gerätezwillingen, Modulzwillingen, Aufträgen und zum Nachrichtenrouting. Dieser Artikel enthält Folgendes:
- Eine Einführung in die wichtigsten Features der IoT Hub Abfragesprache.
- Eine detaillierte Beschreibung der Sprache. Weitere Informationen zur Abfragesprache für das Nachrichtenrouting finden Sie unter IoT Hub-Abfragensyntax für das Routing.
Spezifische Beispiele finden Sie unter Abfragen für IoT Hub-Geräte- und Modul-Twins oder Abfragen für IoT Hub-Aufträge.
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 grundlegenden und standardmäßigen/kostenlosen IoT Hub-Ebenen finden Sie unter Auswählen der richtigen IoT Hub-Ebene und -Größe für Ihre Lösung.
Ausführen IoT Hub-Abfragen
Sie können Abfragen für Ihren IoT-Hub direkt im Azure-Portal ausführen.
- Melden Sie sich beim Azure-Portal an, und navigieren Sie zu Ihrem IoT Hub.
- Wählen Sie Abfragen im Abschnitt Geräteverwaltung des Navigationsmenüs aus.
- Geben Sie eine Abfrage in das Textfeld ein und wählen Sie Abfrage ausführen aus.
Sie können auch Abfragen in Ihren Anwendungen mit den Azure IoT-Dienst-SDKs und Dienst-APIs ausführen.
Beispielcode zur Implementierung von IoT Hub-Abfragen finden Sie im Abschnitt Abfragebeispiele mit den Dienst-SDKs.
Links zu SDK-Referenzseiten und Beispielen finden Sie unter Azure IoT Hub SDKs.
Grundlagen von IoT Hub-Abfragen
Jede IoT Hub-Abfrage besteht aus einer SELECT- und einer FROM-Klausel mit optionalen WHERE- und GROUP BY-Klauseln.
Abfragen werden für eine Sammlung von JSON-Dokumenten ausgeführt, z. B. Gerätezwillinge. Die FROM-Klausel zeigt die Dokumentsammlung an, die durchlaufen werden soll (entweder devices, devices.modules oder devices.jobs).
Anschließend wird der Filter in der WHERE-Klausel angewendet. Mit Aggregationen werden die Ergebnisse dieses Schritts gruppiert, wie in der GROUP BY-Klausel angegeben. Für jede Gruppe wird eine Zeile generiert, wie in der SELECT-Klausel angegeben.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
SELECT-Klausel
Die SELECT <select_list>-Klausel ist in jeder IoT Hub Abfrage erforderlich. Sie gibt an, welche Werte von der Abfrage abgerufen werden. Sie gibt die JSON-Werte an, mit denen die neuen JSON-Objekte erstellt werden sollen.
Für jedes Element der gefilterten (und optional gruppierten) Teilmenge der FROM-Sammlung wird in der Projektionsphase ein neues JSON-Objekt generiert. Dieses Objekt wird mit den in der SELECT-Klausel angegebenen Werten erstellt.
Beispiel:
Rückgabe aller Werte
SELECT *Rückgabe spezifischer Eigenschaften
SELECT DeviceID, LastActivityTimeAggregieren der Ergebnisse einer Abfrage, um eine Anzahl zurückzugeben
SELECT COUNT() as TotalNumber
Derzeit werden Auswahlklauseln, die sich von SELECT unterscheiden, nur in aggregierten Abfragen auf Geräte twins unterstützt.
Die folgende Syntax ist die Grammatik der SELECT-Klausel:
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 eine beliebige Eigenschaft des JSON-Dokuments in der FROM-Auflistung.
Die FROM-Klausel
Die FROM <from_specification> Klausel ist in jeder ioT Hub-Abfrage erforderlich. Dies muss einer von drei Werten sein:
- devices zum Abfragen von Gerätezwillingen
- devices.modules zum Abfragen von Modulzwillingen
- devices.jobs zum Abfragen von Auftragsdetails pro Gerät
Beispiel:
Abrufen aller Gerätezwillinge
SELECT * FROM devices
WHERE-Klausel
Die WHERE <filter_condition> Klausel ist 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. Jedes JSON-Dokument muss die angegebenen Bedingungen als "true " auswerten, damit es in das Ergebnis einbezogen wird.
Beispiel:
Abrufen aller Aufträge, die auf ein bestimmtes Gerät abzielen
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
Die zulässigen Bedingungen werden im Abschnitt "Ausdrücke und Bedingungen " beschrieben.
GROUP BY-Klausel
Die GROUP BY <group_specification> Klausel ist optional. Diese Klausel wird nach dem in der WHERE-Klausel angegebenen Filter und vor der in SELECT angegebenen Projektion ausgeführt. Sie gruppiert Dokumente anhand des Werts eines Attributs. Diese Gruppen werden verwendet, um aggregierte Werte gemäß der SELECT-Klausel zu generieren.
Beispiel:
Zurückgeben der Anzahl der Geräte, die jeden Status für die Telemetriekonfiguration melden
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
Die GROUP BY-Klausel wird derzeit nur für Abfragen von Gerätezwillingen unterstützt.
Achtung
Der Begriff Gruppe wird derzeit als spezielles Schlüsselwort in Abfragen behandelt. Falls Sie als Eigenschaftsname verwendengroup, sollten Sie ihn mit doppelten Klammern umgeben, um Fehler zu vermeiden, wie in diesem Beispiel gezeigt: SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'
Die formale Syntax für GROUP BY lautet:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
Attribute_name bezieht sich auf eine beliebige Eigenschaft des JSON-Dokuments in der FROM-Auflistung.
Paginierung von Abfrageergebnissen
Ein Abfrageobjekt wird mit einer maximalen Seitengröße von kleiner als oder gleich 100 Datensätzen instanziiert. Um mehrere Seiten abzurufen, rufen Sie mehrmals die Methode nextAsTwin für das Node.js SDK oder GetNextAsTwinAsync für das .NET SDK auf. Ein Abfrageobjekt kann mehrere Next-Werte verfügbar machen, abhängig von der Deserialisierungsoption, die von der Abfrage benötigt wird. Ein Abfrageobjekt kann beispielsweise Gerätezwillings- bzw. Auftragsobjekte oder einfachen JSON-Text bei der Verwendung von Projektionen zurückgeben.
Ausdrücke und Bedingungen
Auf hoher Ebene wird ein Ausdruck:
- in eine Instanz eines JSON-Typs (z. B. boolescher Wert, Zahl, Zeichenfolge, Array oder Objekt) ausgewertet.
- Ist definiert durch die Manipulation von Daten, die aus dem JSON-Dokument des Geräts und Konstanten stammen, mithilfe von integrierten Operatoren und Funktionen.
Bedingungen sind Ausdrücke, die als boolescher Wert ausgewertet werden. Jede Konstante, die sich vom booleschen Ausdruck true unterscheidet, wird als false betrachtet. Diese Regel umfasst null, undefined, jede Objekt- oder Arrayinstanz, jede Zeichenfolge und den booleschen Ausdruck false.
Die Syntax für Ausdrücke lautet:
<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:
| Symbol | Definition |
|---|---|
| attribute_name | Eine beliebige Eigenschaft des JSON-Dokuments in der FROM-Sammlung. |
| binary_operator | Ein beliebiger binärer, im Abschnitt Operatoren aufgelisteter Operator. |
| function_name | Eine beliebige im Abschnitt Funktionen aufgelistete Funktion. |
| decimal_literal | Ein Gleitkommawert, ausgedrückt in Dezimalschreibweise. |
| hexadecimal_literal | Eine Zahl, ausgedrückt durch die Zeichenfolge „0x“ gefolgt von einer Zeichenfolge von Hexadezimalzahlen. |
| string_literal | Unicode-Zeichenfolgen, die durch eine Sequenz aus null oder mehr Unicode-Zeichen oder Escapesequenzen dargestellt werden. Zeichenfolgenliterale werden in einfache Anführungszeichen oder doppelte Anführungszeichen eingeschlossen. Zulässige Escapezeichen: \', \", \\, \uXXXX für Unicode-Zeichen, die durch vier Hexadezimalstellen definiert werden. |
Operatoren
Die folgenden Operatoren werden unterstützt:
| Familie | Operatoren |
|---|---|
| Arithmetik | +, -, *, /, % |
| Logisch | UND, ODER, NICHT |
| Vergleich | =, !=, <, >, <=, >=, <> |
Funktionen
Bei Abfragen von Zwillingen und Aufträgen wird nur folgende Funktion unterstützt:
| Funktion | BESCHREIBUNG |
|---|---|
| IS_DEFINED(Eigenschaft) | Gibt einen Wert vom Typ Boolean zurück, der angibt, ob der Eigenschaft ein Wert zugewiesen ist (einschließlich null). |
In Routenbedingungen werden die folgenden mathematischen Funktionen unterstützt:
| Funktion | BESCHREIBUNG |
|---|---|
| ABS(x) | Gibt den absoluten (positiven) Wert des angegebenen numerischen Ausdrucks zurück. |
| EXP(x) | Gibt den Exponentialwert des angegebenen numerischen Ausdrucks (e^x) zurück. |
| Potenz(x,y) | Gibt den Wert des angegebenen Ausdrucks gemäß der angegebenen Potenz (x^y) zurück. |
| SQUARE(x) | Gibt die Quadratwurzel des angegebenen numerischen Werts zurück. |
| CEILING(x) | Gibt den kleinsten ganzzahligen Wert zurück, der größer oder gleich dem angegebenen numerischen Ausdruck ist. |
| FLOOR(x) | Gibt die größte ganze Zahl zurück, die kleiner oder gleich dem angegebenen numerischen Ausdruck ist. |
| SIGN(x) | Gibt das positive Vorzeichen (+1), null (0) oder das negative Vorzeichen (-1) des angegebenen numerischen Ausdrucks zurück. |
| SQRT(x) | Gibt die Quadratwurzel des angegebenen numerischen Werts zurück. |
In Routenbedingungen werden die folgenden Typüberprüfungs- und Umwandlungsfunktionen unterstützt:
| Funktion | BESCHREIBUNG |
|---|---|
| AS_NUMBER | Konvertiert die Eingabezeichenfolge in eine Zahl.
noop, wenn die Eingabe eine Zahl ist; Undefined, wenn die Zeichenfolge keine Zahl darstellt. |
| IS_ARRAY | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Array“ ist. |
| IS_BOOL | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „boolesch“ ist. |
| IS_DEFINED | Gibt einen Wert vom Typ Boolean zurück, der angibt, ob die Eigenschaft ein Wert ist. Diese Funktion wird nur unterstützt, wenn es sich bei dem Wert um einen primitiven Typ handelt. Primitive Typen umfassen Zeichenfolgen, boolesche Werte, numerische Werte und null. DateTime, Objekttypen und Arrays werden nicht unterstützt. |
| IS_NULL | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „NULL“ ist. |
| IS_NUMBER | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Zahl“ ist. |
| IS_OBJECT | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „JSON-Objekt“ ist. |
| IS_PRIMITIVE | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck ein Grundtyp ist (Zeichenfolge, boolesch, numerisch oder null). |
| IS_STRING | Gibt einen booleschen Wert zurück, der angibt, ob der angegebene Ausdruck vom Typ „Zeichenfolge“ ist. |
In Routenbedingungen werden die folgenden Zeichenfolgenfunktionen unterstützt:
| Funktion | BESCHREIBUNG |
|---|---|
| VERKETTEN(x, y, ...) | Gibt eine Zeichenfolge zurück, die das Ergebnis der Verkettung von zwei oder mehr Zeichenfolgenwerten darstellt. |
| LENGTH(x) | Gibt die Anzahl der Zeichen im angegebenen Zeichenfolgenausdruck zurück. |
| LOWER(x) | Gibt eine Zeichenfolge zurück, nachdem Großbuchstaben in Kleinbuchstaben konvertiert wurden. |
| UPPER(x) | Gibt eine Zeichenfolge zurück, nachdem Kleinbuchstaben in Großbuchstaben konvertiert wurden. |
| SUBSTRING(Zeichenfolge, Start [, Länge]) | 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. |
| INDEX_OF(Zeichenfolge, 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. |
| BEGINNT_MIT(x, y) | Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck mit dem zweiten beginnt. |
| ENDEN_MIT(x, y) | Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck mit dem zweiten endet. |
| CONTAINS(x,y) | Gibt einen booleschen Wert zurück, um anzugeben, ob der erste Zeichenfolgenausdruck den zweiten enthält. |
Abfragebeispiele mit den Dienst-SDKs
C#-Beispiel
Die Abfragefunktionalität wird vom Azure IoT Hub Service SDK für .NET in der klasse RegistryManager verfügbar gemacht.
Hier ein Beispiel einer einfachen Abfrage:
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 Abfrageobjekt wird mit den parametern instanziiert, die im Abschnitt "Abfrageergebnisse paginierung " erwähnt werden. Mehrere Seiten werden durch mehrfaches Aufrufen der GetNextAsTwinAsync Methoden abgerufen.
Node.js-Beispiel
Die Abfragefunktionalität wird vom Azure IoT Hub Service SDK für Node.js im objekt Registry verfügbar gemacht.
Hier ein Beispiel einer einfachen Abfrage:
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 Abfrageobjekt wird mit den parametern instanziiert, die im Abschnitt "Abfrageergebnisse paginierung " erwähnt werden. Mehrere Seiten werden durch mehrfaches Aufrufen der nextAsTwin Methode abgerufen.
Abfragen für IoT Hub Geräte- und Modul-Twins
Geräte-Zwillinge und Modul-Zwillinge können beliebige JSON-Objekte als Tags und Eigenschaften enthalten. mit IoT Hub können Sie Geräte-Twins und Modul-Twins als einzelnes JSON-Dokument abfragen, das alle Twin-Informationen enthält.
Hier ist ein Beispiel für einen IoT-Hub-Gerätetwin (ein Modultwin wäre ähnlich, nur mit einem Parameter für 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äte-Twin-Abfragen
IoT Hub stellt die Geräte twins als Dokumentsammlung namens devices zur Verfügung. Die grundlegendste Abfrage ruft beispielsweise den gesamten Satz von Geräte twins ab:
SELECT * FROM devices
Hinweis
Azure IoT SDKs unterstützen das Paging großer Ergebnisse.
Sie können die Ergebnisse einer Abfrage mithilfe der SELECT-Klausel aggregieren. Die folgende Abfrage ruft beispielsweise die Gesamtzahl der Geräte in einem IoT-Hub ab:
SELECT COUNT() as totalNumberOfDevices FROM devices
Filter die Ergebnisse der Abfrage mithilfe der WHERE-Klausel. Um zum Beispiel Geräte-Zwillinge zu empfangen, bei denen das location.region Tag auf US festgelegt ist, verwenden Sie die folgende Abfrage:
SELECT * FROM devices
WHERE tags.location.region = 'US'
Erstellen Sie komplexe WHERE-Klauseln mithilfe boolescher Operatoren und arithmetischer Vergleiche. Die folgende Abfrage ruft beispielsweise Geräte-Zwillinge in den USA ab, die so konfiguriert sind, dass sie Telemetrie seltener als einmal pro Minute senden.
SELECT * FROM devices
WHERE tags.location.region = 'US'
AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60
Sie können auch Arraykonstanten mit den Operatoren IN und NIN (nicht in) verwenden. Die folgende Abfrage ruft beispielsweise Geräte-Zwillinge ab, die entweder WLAN oder kabelgebundene Konnektivität melden:
SELECT * FROM devices
WHERE properties.reported.connectivity IN ['wired', 'wifi']
Es ist häufig erforderlich, alle Gerätezwillinge zu identifizieren, die eine bestimmte Eigenschaft enthalten. IoT Hub unterstützt die Funktion is_defined() zu diesem Zweck. Die folgende Abfrage ruft beispielsweise Geräte twins ab, die die connectivity Eigenschaft definieren:
SELECT * FROM devices
WHERE is_defined(properties.reported.connectivity)
Im ABSCHNITT WHERE-Klausel finden Sie den vollständigen Verweis auf die Filterfunktionen.
Die Gruppierung wird ebenfalls unterstützt. Die folgende Abfrage gibt beispielsweise die Anzahl der Geräte in jedem Telemetriekonfigurationsstatus zurück:
SELECT properties.reported.telemetryConfig.status AS status,
COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status
Diese Gruppierungsabfrage würde ein Ergebnis wie im folgenden Beispiel zurückgeben:
[
{
"numberOfDevices": 3,
"status": "Success"
},
{
"numberOfDevices": 2,
"status": "Pending"
},
{
"numberOfDevices": 1,
"status": "Error"
}
]
In diesem Beispiel meldeten drei Geräte eine erfolgreiche Konfiguration, zwei wenden weiterhin die Konfiguration an, und eines hat einen Fehler gemeldet.
Projektionsabfragen ermöglichen Entwicklern, nur die Eigenschaften zurückzugeben, die sie interessieren. Wenn Sie beispielsweise die letzte Aktivitätszeit zusammen mit der Geräte-ID aller aktivierten Geräte abrufen möchten, die getrennt sind, verwenden Sie die folgende Abfrage:
SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'
Das Ergebnis dieser Abfrage würde wie im folgenden Beispiel aussehen:
[
{
"deviceId": "AZ3166Device",
"lastActivityTime": "2021-05-07T00:50:38.0543092Z"
}
]
Modultwin-Abfragen
Das Abfragen von Modul-Twins ähnelt dem Abfragen von Geräte-Twins, aber mit einer anderen Sammlung/einem anderen Namespace; statt von devices abfragen Sie von devices.modules:
SELECT * FROM devices.modules
Die Verknüpfung zwischen geräten und geräte.modules-Sammlungen ist nicht zulässig. Wenn Sie Modul-Zwillinge über Geräte hinweg abfragen möchten, erfolgt dies auf der Basis von Tags. Die folgende Abfrage gibt alle Modul-Zwillinge auf allen Geräten, die den Scan-Status haben, zurück.
SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'
Die folgende Abfrage gibt alle Modul twins mit dem Scanstatus zurück, aber nur auf der angegebenen Teilmenge der Geräte:
SELECT * FROM devices.modules
WHERE properties.reported.status = 'scanning'
AND deviceId IN ['device1', 'device2']
Twin-Abfragebeschränkungen
Important
Abfrageergebnisse sind letztlich konsistente Operationen, und Verzögerungen von bis zu 30 Minuten sollten toleriert werden. In den meisten Fällen liefert die Doppelanfrage Ergebnisse innerhalb von ein paar Sekunden zurück. IoT Hub sorgt bei allen Vorgängen für eine möglichst niedrige Latenz. Abhängig von den Netzwerkbedingungen und aufgrund weiterer unvorhersehbarer Faktoren kann eine bestimmte Wartezeit jedoch nicht garantiert werden.
Eine Alternative zu Twin-Abfragen ist das Abfragen einzelner Geräte-Twins anhand ihrer ID mithilfe der get twin REST-API. Diese API gibt immer die neuesten Werte zurück und weist höhere Einschränkungsgrenzwerte auf. Sie können die REST-API direkt ausstellen oder die entsprechende Funktionalität in einem der Azure IoT Hub Service SDKs verwenden.
Abfrageausdrücke können maximal 8.192 Zeichen lang sein.
Derzeit werden Vergleiche nur zwischen primitiven Typen (keine Objekte) unterstützt, zum Beispiel ... WHERE properties.desired.config = properties.reported.config nur, wenn diese Eigenschaften primitive Werte aufweisen.
Es wird empfohlen, in keinem Szenario eine Abhängigkeit von lastActivityTime in den Geräteidentitätseigenschaften für Twin-Abfragen zu verwenden. Dieses Feld garantiert keine genaue Anzeige des Gerätestatus. Verwenden Sie stattdessen IoT Device Lifecycle-Ereignisse, um den Gerätestatus und Aktivitäten zu verwalten. Informationen zur Verwendung von IoT Hub Lifecycle-Ereignissen in Ihrer Lösung finden Sie unter React to IoT Hub events by using Event Grid to trigger actions.
Hinweis
Vermeiden Sie annahmen über die maximale Latenz dieses Vorgangs. Weitere Informationen zum Erstellen Ihrer Lösung unter Berücksichtigung der Latenz finden Sie unter Latenzlösungen .
Abfragen für IoT Hub Aufträge
Aufträge bieten eine Möglichkeit zum Ausführen von Vorgängen auf Gruppen von Geräten. Jeder Gerätetwin enthält die Informationen über die Jobs, die auf ihn ausgerichtet sind, in einer Sammlung namens jobs. mit IoT Hub können Sie Aufträge als einzelnes JSON-Dokument abfragen, das alle Zwillingsinformationen enthält.
Hier ist ein Beispiel für ioT Hub-Gerät Twin, das Teil eines Auftrags namens myJobId ist:
{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"tags": {
...
},
"properties": {
...
},
"jobs": [
{
"deviceId": "myDeviceId",
"jobId": "myJobId",
"jobType": "scheduleUpdateTwin",
"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
}
},
...
]
}
Derzeit kann diese Auflistung als devices.jobs in der IoT Hub Abfragesprache abfragt werden.
Important
Derzeit wird die Auftragseigenschaft beim Abfragen von Geräte-Twins nicht zurückgegeben. Das heißt, Abfragen, die enthalten FROM devices. Die Auftragseigenschaft kann nur direkt mit Abfragen unter Verwendung von FROM devices.jobs zugegriffen werden.
Die folgende Abfrage gibt beispielsweise alle Aufträge (über- und geplant) zurück, die sich auf ein einzelnes Gerät auswirken:
SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
Beachten Sie, dass diese Abfrage den gerätespezifischen Status (und möglicherweise die direkte Methodenantwort) der zurückgegebenen einzelnen Aufträge bereitstellt.
Es ist auch möglich, mit beliebigen booleschen Bedingungen nach allen Objekteigenschaften in der devices.jobs Auflistung zu filtern.
Die folgende Abfrage ruft beispielsweise alle abgeschlossenen Geräte-Twin-Updateaufträge ab, die nach September 2016 für ein bestimmtes Gerät erstellt wurden:
SELECT * FROM devices.jobs
WHERE devices.jobs.deviceId = 'myDeviceId'
AND devices.jobs.jobType = 'scheduleUpdateTwin'
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.
SELECT * FROM devices.jobs
WHERE devices.jobs.jobId = 'myJobId'
Einschränkungen der Auftragsabfrage
Abfrageausdrücke können maximal 8.192 Zeichen lang sein.
Derzeit unterstützen Abfragen auf devices.jobs Folgendes nicht:
- Daher sind nur Projektionen
SELECT *möglich. - Bedingungen, die zusätzlich zu Auftragseigenschaften auf das Gerät Twin verweisen (siehe vorherigen Abschnitt).
- Aggregationen, z. B. Anzahl, Mittelwert und Gruppieren nach.
Verwandte Inhalte
- Erfahren Sie mehr über das Routing von Nachrichten basierend auf Nachrichteneigenschaften oder dem Nachrichtentext mit der IoT Hub-Abfragesyntax für das Nachrichtenrouting.