IoT Hub-querytaal voor apparaat- en moduledubbels, taken en-berichtroutering
IoT Hub biedt een krachtige SQL-achtige taal voor het ophalen van informatie over apparaatdubbels, moduledubbels, taken en berichtroutering. In dit artikel wordt het volgende beschreven:
- Een inleiding tot de belangrijkste functies van de IoT Hub-querytaal en
- De gedetailleerde beschrijving van de taal. Zie query's in berichtroutering voor meer informatie over de querytaal voor berichtroutering.
Zie Query's voor apparaat- en moduledubbels of query's voor taken voor specifieke voorbeelden.
Notitie
Sommige van de functies die in dit artikel worden genoemd, zoals cloud-naar-apparaat-berichten, apparaatdubbels en apparaatbeheer, zijn alleen beschikbaar in de standaardlaag van IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.
IoT Hub-query's uitvoeren
U kunt query's uitvoeren op uw IoT-hub rechtstreeks in Azure Portal.
- Meld u aan bij de Azure-portal en ga naar uw IoT Hub.
- Selecteer Query's in de sectie Apparaatbeheer van het navigatiemenu.
- Voer uw query in het tekstvak in en selecteer Query uitvoeren.
U kunt ook query's in uw toepassingen uitvoeren met behulp van de SDK's en service-API's van de Azure IoT-service.
Zie bijvoorbeeld code voor het implementeren van IoT Hub-query's de queryvoorbeelden met de sectie service-SDK's .
Zie Azure IoT SDK's voor koppelingen naar SDK-referentiepagina's en voorbeelden.
Basisbeginselen van een IoT Hub-query
Elke IoT Hub-query bestaat uit SELECT- en FROM-componenten, met optionele WHERE- en GROUP BY-componenten.
Query's worden uitgevoerd op een verzameling JSON-documenten, bijvoorbeeld apparaatdubbels. De FROM-component geeft aan dat de documentverzameling moet worden ge curseerd (apparaten, devices.modules of devices.jobs).
Vervolgens wordt het filter in de WHERE-component toegepast. Met aggregaties worden de resultaten van deze stap gegroepeerd zoals opgegeven in de GROUP BY-component. Voor elke groep wordt een rij gegenereerd zoals opgegeven in de SELECT-component.
SELECT <select_list>
FROM <from_specification>
[WHERE <filter_condition>]
[GROUP BY <group_specification>]
SELECT-component
De SELECT <select_list-component> is vereist in elke IoT Hub-query. Hiermee geeft u op welke waarden uit de query worden opgehaald. Hiermee geeft u de JSON-waarden op die moeten worden gebruikt voor het genereren van nieuwe JSON-objecten. Voor elk element van de gefilterde (en optioneel gegroepeerde) subset van de FROM-verzameling genereert de projectiefase een nieuw JSON-object. Dit object wordt samengesteld met de waarden die zijn opgegeven in de SELECT-component.
Voorbeeld:
Alle waarden retourneren
SELECT *Specifieke eigenschappen retourneren
SELECT DeviceID, LastActivityTimeDe resultaten van een query aggregeren om een telling te retourneren
SELECT COUNT() as TotalNumber
Op dit moment worden selectiecomponenten die afwijken van SELECT alleen ondersteund in statistische query's op apparaatdubbels.
De volgende syntaxis is de grammatica van de SELECT-component:
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 verwijst naar een eigenschap van het JSON-document in de VERZAMELING FROM.
FROM-component
De COMPONENT FROM <from_specification> is vereist in elke IoT Hub-query. Dit moet een van de volgende drie waarden zijn:
- apparaten om een query uit te voeren op apparaatdubbels
- devices.modules om query's uit te voeren op moduledubbels
- devices.jobs om de taakgegevens per apparaat op te vragen
Voorbeeld:
Alle apparaatdubbels ophalen
SELECT * FROM devices
WHERE-component
De WHERE <filter_condition-component> is optioneel. Hiermee geeft u een of meer voorwaarden op waaraan de JSON-documenten in de FROM-verzameling moeten voldoen om als onderdeel van het resultaat te worden opgenomen. Elk JSON-document moet de opgegeven voorwaarden 'waar' evalueren om in het resultaat te worden opgenomen.
Voorbeeld:
Alle taken ophalen die zijn gericht op een specifiek apparaat
SELECT * FROM devices.jobs WHERE devices.jobs.deviceId = 'myDeviceId'
De toegestane voorwaarden worden beschreven in de sectie expressies en voorwaarden .
Clausule GROUP BY
De component GROUP BY <group_specification> is optioneel. Deze component wordt uitgevoerd na het filter dat is opgegeven in de WHERE-component en vóór de projectie die is opgegeven in de SELECT. Documenten worden gegroepeerd op basis van de waarde van een kenmerk. Deze groepen worden gebruikt voor het genereren van geaggregeerde waarden zoals opgegeven in de SELECT-component.
Voorbeeld:
Het aantal apparaten retourneren dat elke telemetrieconfiguratiestatus rapporteert
SELECT properties.reported.telemetryConfig.status AS status, COUNT() AS numberOfDevices FROM devices GROUP BY properties.reported.telemetryConfig.status
Momenteel wordt de GROUP BY-component alleen ondersteund bij het uitvoeren van query's op apparaatdubbels.
Let op
De term group wordt momenteel behandeld als een speciaal trefwoord in query's. Als u de naam van uw eigenschap gebruikt group , kunt u overwegen om deze te omringen met dubbele haken om fouten te voorkomen, bijvoorbeeld SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'.
De formele syntaxis voor GROUP BY is:
GROUP BY <group_by_element>
<group_by_element> :==
attribute_name
| < group_by_element > '.' attribute_name
Attribute_name verwijst naar een eigenschap van het JSON-document in de VERZAMELING FROM.
Paginering van queryresultaten
Een queryobject wordt geïnstantieerd met een maximale paginagrootte van minder dan of gelijk aan 100 records. Als u meerdere pagina's wilt verkrijgen, roept u de volgendeAsTwin aan op Node.js SDK of GetNextAsTwinAsync op de .Net SDK-methode meerdere keren. Een queryobject kan meerdere volgende waarden weergeven, afhankelijk van de deserialisatieoptie die is vereist voor de query. Een queryobject kan bijvoorbeeld apparaatdubbel- of taakobjecten retourneren, of gewone JSON bij het gebruik van projecties.
Expressies en voorwaarden
Een expressie op hoog niveau:
- Evalueert naar een exemplaar van een JSON-type (zoals Booleaanse waarde, getal, tekenreeks, matrix of object).
- Wordt gedefinieerd door gegevens te bewerken die afkomstig zijn van het JSON-document en constanten van het apparaat met behulp van ingebouwde operators en functies.
Voorwaarden zijn expressies die resulteren in een Booleaanse waarde. Elke constante die anders is dan Booleaanse waar , wordt beschouwd als onwaar. Deze regel omvat null, undefined, any object or array instance, any string, and the Boolean false.
De syntaxis voor expressies 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>]+ ']'
Raadpleeg de volgende tabel om te begrijpen waar elk symbool in de syntaxis van de expressies voor staat:
| Symbool | Definitie |
|---|---|
| attribute_name | Elke eigenschap van het JSON-document in de FROM-verzameling . |
| binary_operator | Een binaire operator die wordt vermeld in de sectie Operators . |
| function_name | Elke functie die wordt vermeld in de sectie Functions . |
| decimal_literal | Een float uitgedrukt in decimale notatie. |
| hexadecimal_literal | Een getal uitgedrukt door de tekenreeks 0x, gevolgd door een tekenreeks met hexadecimale cijfers. |
| string_literal | Unicode-tekenreeksen die worden vertegenwoordigd door een reeks nul of meer Unicode-tekens of escapereeksen. Letterlijke tekenreeksen staan tussen enkele aanhalingstekens of dubbele aanhalingstekens. Toegestane escapes: \', \", voor \\\uXXXX Unicode-tekens die zijn gedefinieerd door vier hexadecimale cijfers. |
Operators
De volgende operators worden ondersteund:
| Gezin | Operators |
|---|---|
| Rekenkundig | +, -, *, /, % |
| Logisch | EN, OF, NIET |
| Vergelijking | =, !=, <, ><=, >=,<> |
Functions
Bij het uitvoeren van query's op dubbels en taken is de enige ondersteunde functie:
| Functie | Beschrijving |
|---|---|
| IS_DEFINED(eigenschap) | Hiermee wordt een Booleaanse waarde geretourneerd die aangeeft of aan de eigenschap een waarde is toegewezen (inclusief null). |
In routes worden de volgende wiskundige functies ondersteund:
| Functie | Beschrijving |
|---|---|
| ABS(x) | Retourneert de absolute (positieve) waarde van de opgegeven numerieke expressie. |
| EXP(x) | Retourneert de exponentiële waarde van de opgegeven numerieke expressie (e^x). |
| POWER(x,y) | Retourneert de waarde van de opgegeven expressie naar de opgegeven macht (x^y). |
| SQUARE(x) | Retourneert het vierkant van de opgegeven numerieke waarde. |
| PLAFOND(x) | Retourneert het kleinste gehele getal dat groter is dan of gelijk is aan de opgegeven numerieke expressie. |
| FLOOR(x) | Retourneert het grootste gehele getal dat kleiner is dan of gelijk is aan de opgegeven numerieke expressie. |
| SIGN(x) | Retourneert het positieve teken (+1), nul (0) of negatief (-1) van de opgegeven numerieke expressie. |
| SQRT(x) | Retourneert de vierkantswortel van de opgegeven numerieke waarde. |
In routes worden de volgende typecontrole- en cast-functies ondersteund:
| Functie | Beschrijving |
|---|---|
| AS_NUMBER | Converteert de invoertekenreeks naar een getal. noop als invoer een getal is; Undefined als een tekenreeks geen getal vertegenwoordigt. |
| IS_ARRAY | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een matrix is. |
| IS_BOOL | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een Booleaanse waarde is. |
| IS_DEFINED | Retourneert een Booleaanse waarde die aangeeft of aan de eigenschap een waarde is toegewezen. Deze functie wordt alleen ondersteund wanneer de waarde een primitief type is. Primitieve typen zijn tekenreeks, Booleaanse waarde, numeriek of null. DateTime, objecttypen en matrices worden niet ondersteund. |
| IS_NULL | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie null is. |
| IS_NUMBER | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een getal is. |
| IS_OBJECT | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een JSON-object is. |
| IS_PRIMITIVE | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een primitieve expressie is (tekenreeks, Booleaanse waarde, numeriek of null). |
| IS_STRING | Retourneert een Booleaanse waarde die aangeeft of het type van de opgegeven expressie een tekenreeks is. |
In routes worden de volgende tekenreeksfuncties ondersteund:
| Functie | Beschrijving |
|---|---|
| TEKST.SAMENV(x, y, ...) | Retourneert een tekenreeks die het resultaat is van het samenvoegen van twee of meer tekenreekswaarden. |
| LENGTH(x) | Retourneert het aantal tekens van de opgegeven tekenreeksexpressie. |
| LOWER(x) | Retourneert een tekenreeksexpressie na het converteren van tekens in hoofdletters naar kleine letters. |
| UPPER(x) | Retourneert een tekenreeksexpressie na het converteren van tekens in kleine letters naar hoofdletters. |
| SUBTEKENREEKS(tekenreeks; begin [, lengte]) | Retourneert een deel van een tekenreeksexpressie vanaf de opgegeven positie op nul en blijft de opgegeven lengte, of aan het einde van de tekenreeks. |
| INDEX_OF(tekenreeks, fragment) | Retourneert de beginpositie van het eerste exemplaar van de tweede tekenreeksexpressie in de eerste opgegeven tekenreeksexpressie of -1 als de tekenreeks niet wordt gevonden. |
| STARTSWITH(x, y) | Retourneert een Booleaanse waarde die aangeeft of de eerste tekenreeksexpressie begint met de tweede. |
| ENDSWITH(x, y) | Retourneert een Booleaanse waarde die aangeeft of de eerste tekenreeksexpressie eindigt op de tweede. |
| CONTAINS(x,y) | Retourneert een Booleaanse waarde die aangeeft of de eerste tekenreeksexpressie de tweede bevat. |
Queryvoorbeelden met de service-SDK's
C#-voorbeeld
De queryfunctionaliteit wordt weergegeven door de C#-service-SDK in de klasse RegistryManager .
Hier volgt een voorbeeld van een eenvoudige 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
}
}
Het queryobject wordt geïnstantieerd met de parameters die worden vermeld in de sectie queryresultatenpaginering . Meerdere pagina's worden opgehaald door de GetNextAsTwinAsync-methoden meerdere keren aan te roepen.
Node.js voorbeeld
De queryfunctionaliteit wordt weergegeven door de Azure IoT-service-SDK voor Node.js in het registerobject .
Hier volgt een voorbeeld van een eenvoudige 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);
Het queryobject wordt geïnstantieerd met de parameters die worden vermeld in de sectie queryresultatenpaginering . Meerdere pagina's worden opgehaald door de volgendeAsTwin-methode meerdere keren aan te roepen.
Volgende stappen
- Meer informatie over routeringsberichten op basis van berichteigenschappen of berichttekst met de syntaxis van de ioT Hub-berichtrouteringsquery.
- Bekijk specifieke voorbeelden van query's voor apparaat- en moduledubbels of query's voor taken.