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 vindt u het volgende:
- 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 lagen Basic en Standard/free IoT Hub.
Query's IoT Hub uitvoeren
U kunt query's rechtstreeks in de Azure Portal uitvoeren op uw IoT-hub.
- 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 uitvoeren in uw toepassingen met behulp van de Azure IoT-service-SDK's en service-API's.
Zie de sectie Queryvoorbeelden met de service-SDK's voor een voorbeeldcode die IoT Hub query's implementeert.
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 op welke documentverzameling moet worden genadigeerd ( 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 wordt opgegeven welke waarden worden opgehaald uit de query. Hiermee worden de JSON-waarden opgegeven 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 is samengesteld met de waarden die zijn opgegeven in de SELECT-component.
Bijvoorbeeld:
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 aggregatiequery'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 from-verzameling.
FROM-component
De COMPONENT FROM <from_specification> is vereist in elke IoT Hub-query. Dit moet een van de drie waarden zijn:
- apparaten om een query uit te voeren op apparaatdubbels
- devices.modules om query's uit te voeren op moduledubbels
- devices.jobs taakgegevens per apparaat opvragen
Bijvoorbeeld:
Alle apparaatdubbels ophalen
SELECT * FROM devices
WHERE-component
De component WHERE <filter_condition> is optioneel. Hiermee worden een of meer voorwaarden opgegeven 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 evalueren op 'true' om in het resultaat te worden opgenomen.
Bijvoorbeeld:
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 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.
Bijvoorbeeld:
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
Op dit moment wordt de GROUP BY-component alleen ondersteund bij het uitvoeren van query's op apparaatdubbels.
Waarschuwing
De term group wordt momenteel behandeld als een speciaal trefwoord in query's. Als u als de naam van de eigenschap gebruikt group , kunt u overwegen om deze te plaatsen met dubbele haken om fouten te voorkomen, SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'bijvoorbeeld .
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 from-verzameling.
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 methode nextAsTwin op Node.js SDK of GetNextAsTwinAsync op .Net SDK meerdere keren aan. Een queryobject kan meerdere volgende waarden weergeven, afhankelijk van de deserialisatieoptie die voor de query is vereist. Een queryobject kan bijvoorbeeld apparaatdubbel- of taakobjecten of gewone JSON retourneren bij het gebruik van projecties.
Expressies en voorwaarden
Op een hoog niveau, een expressie:
- 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. Een andere constante dan Booleaanse waarde waar wordt beschouwd als onwaar. Deze regel omvat null, niet-gedefinieerd, elk object- of matrixexemplaren, een tekenreeks en de Booleaanse waarde onwaar.
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 voor expressies voor staat:
| Symbool | Definitie |
|---|---|
| attribute_name | Een eigenschap van het JSON-document in de verzameling FROM . |
| binary_operator | Een binaire operator die wordt vermeld in de sectie Operators . |
| function_name | Een functie die wordt vermeld in de sectie Functies . |
| decimal_literal | Een float uitgedrukt in decimale notatie. |
| hexadecimal_literal | Een getal dat wordt uitgedrukt door de tekenreeks '0x', gevolgd door een reeks hexadecimale cijfers. |
| string_literal | Unicode-tekenreeksen die worden vertegenwoordigd door een reeks van nul of meer Unicode-tekens of escape-reeksen. Letterlijke tekenreeksen worden tussen enkele aanhalingstekens of dubbele aanhalingstekens geplaatst. Toegestane escapes: \', \", \\, \uXXXX voor Unicode-tekens die zijn gedefinieerd door vier hexadecimale cijfers. |
Operators
De volgende operators worden ondersteund:
| Familie | 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) | Retourneert een Booleaanse waarde die aangeeft of aan de eigenschap een waarde is toegewezen (inclusief null). |
In routesvoorwaarden 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). |
| MACHT(x;y) | Retourneert de waarde van de opgegeven expressie naar de opgegeven macht (x^y). |
| VIERKANT(x) | Retourneert het kwadraat 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 (+1), nulteken (0) of negatief (-1) van de opgegeven numerieke expressie. |
| SQRT(x) | Retourneert de vierkantswortel van de opgegeven numerieke waarde. |
In de voorwaarden voor routes worden de volgende typen controle- en cast-functies ondersteund:
| Functie | Beschrijving |
|---|---|
| AS_NUMBER | Converteert de invoertekenreeks naar een getal. noop als invoer een getal is; Undefined als 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 als de waarde een primitief type is. Primitieve typen zijn tekenreeks, Booleaans, numeriek of null. Datum/tijd, 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 primitief 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 routesvoorwaarden 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. |
| LENGTE(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. |
| SUBSTRING(tekenreeks; begin [, lengte]) | Retourneert een deel van een tekenreeksexpressie vanaf de opgegeven positie op basis van teken nul en gaat door tot de opgegeven lengte of tot het einde van de tekenreeks. |
| INDEX_OF(tekenreeks, fragment) | Retourneert de beginpositie van het eerste exemplaar van de tweede tekenreeksexpressie binnen 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 paginering van queryresultaten . Meerdere pagina's worden opgehaald door de methoden GetNextAsTwinAsync 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 paginering van queryresultaten . Meerdere pagina's worden opgehaald door de methode nextAsTwin meerdere keren aan te roepen.
Volgende stappen
- Meer informatie over het routeren van berichten op basis van berichteigenschappen of berichttekst met de IoT Hub berichtrouteringsquerysyntaxis.
- Bekijk specifieke voorbeelden van Query's voor apparaat- en moduledubbels of Query's voor taken.