IoT-központ üzenet-útválasztásának lekérdezési szintaxisa
Az üzenet-útválasztás lehetővé teszi, hogy a felhasználók különböző adattípusokat, például az eszköz telemetriai üzeneteit, az eszköz életciklus-eseményeit és az ikereszköz-változási eseményeket különböző végpontokra irányítson át. Gazdag lekérdezéseket is alkalmazhat ezekre az adatokra, mielőtt útválasztást alkalmaz, hogy megkapja az Önnek fontos adatokat. Ez a cikk az IoT Hub üzenet-útválasztás lekérdezési nyelvét ismerteti, és néhány gyakori lekérdezési mintát tartalmaz.
Megjegyzés
A cikkben említett egyes funkciók, például a felhő–eszköz irányú üzenetküldés, az ikereszközök és az eszközfelügyelet csak a standard szintű IoT Hubon érhető el. Az alapszintű és standard/ingyenes IoT Hub szintekkel kapcsolatos további információkért lásd: A megoldáshoz megfelelő IoT Hub szint kiválasztása.
Az üzenet útválasztásával lekérdezheti az üzenet tulajdonságait és az üzenet törzsét, valamint az ikereszköz címkéinek és ikereszköz-tulajdonságainak adatait. Ha az üzenettörzs nem JSON formátumban van, az üzenet útválasztása továbbra is irányíthatja az üzenetet, de a lekérdezések nem alkalmazhatók az üzenettörzsre. A lekérdezések logikai kifejezésekként vannak leírva, ahol ha igaz, a lekérdezés sikeres lesz, és átirányítja az összes bejövő adatot; ellenkező esetben a lekérdezés meghiúsul, és a bejövő adatok nincsenek átirányítva. Ha a kifejezés null értékű vagy nem definiált értéket ad ki, logikai hamis értékként lesz kezelve, és hibát generál a IoT Hub erőforrásnaplókat irányít. A lekérdezés szintaxisának helyesnek kell lennie ahhoz, hogy az útvonal menthető és kiértékelhető legyen.
Lekérdezés üzenettulajdonságok alapján
IoT Hub az összes eszközről felhőbe irányuló üzenetküldés közös formátumát határozza meg a protokollok közötti együttműködés érdekében. IoT Hub az üzenet következő JSON-ábrázolását feltételezi. A rendszertulajdonságok az összes felhasználóhoz hozzáadódnak, és azonosítják az üzenet tartalmát. A felhasználók szelektíven adhatnak hozzá alkalmazástulajdonságokat az üzenethez. Javasoljuk, hogy egyedi tulajdonságneveket használjon, mert IoT Hub eszközről a felhőbe irányuló üzenetküldés nem megkülönbözteti a kis- és nagybetűket. Ha például több azonos nevű tulajdonsággal rendelkezik, IoT Hub csak az egyik tulajdonságot küldi el.
{
"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}}"
}
}
Rendszertulajdonságok
A rendszertulajdonságok segítenek azonosítani az üzenetek tartalmát és forrását, amelyek közül néhányat az alábbi táblázatban ismertetünk:
Tulajdonság | Típus | Description |
---|---|---|
contentType | sztring | A felhasználó határozza meg az üzenet tartalomtípusát. Ha engedélyezni szeretné a lekérdezést az üzenettörzsben, ezt az értéket a következő értékre kell állítani: application/JSON . |
contentEncoding | sztring | A felhasználó megadja az üzenet kódolási típusát. Ha a contentType tulajdonság értéke application/JSON , akkor az engedélyezett értékek a , UTF-16 és UTF-32 .UTF-8 |
iothub-connection-device-id | sztring | Ezt az értéket IoT Hub állítja be, és azonosítja az eszköz azonosítóját. A lekérdezéshez használja a következőt $connectionDeviceId : . |
iothub-connection-module-id | sztring | Ezt az értéket a IoT Hub állítja be, és azonosítja a peremhálózati modul azonosítóját. A lekérdezéshez használja a következőt $connectionModuleId : . |
iothub-enqueuedtime | sztring | Ezt az értéket a IoT Hub állítja be, és az üzenet utc-ben történő leküldésének tényleges időpontját jelöli. A lekérdezéshez használja a következőt $enqueuedTime : . |
dt-dataschema | sztring | Ezt az értéket az eszközről a felhőbe irányuló üzenetek IoT Hub állítja be. Az eszközkapcsolatban beállított eszközmodell-azonosítót tartalmazza. A lekérdezéshez használja a következőt $dt-dataschema : . |
dt-subject | sztring | Az eszközről a felhőbe irányuló üzeneteket küldő összetevő neve. A lekérdezéshez használja a következőt $dt-subject : . |
További információ a többi elérhető rendszertulajdonságról: IoT Hub üzenetek létrehozása és olvasása.
Az alkalmazás tulajdonságai
Az alkalmazástulajdonságok felhasználó által definiált sztringek, amelyek hozzáadhatók az üzenethez. Ezek a mezők nem kötelezőek.
Üzenettulajdonságok lekérdezési kifejezései
Az üzenetrendszer tulajdonságainak lekérdezését előtaggal kell ellátni a $
szimbólummal. Az alkalmazástulajdonságok lekérdezései a nevükkel érhetők el, és nem szabad a szimbólummal előtaggal $
ellátni őket. Ha egy alkalmazástulajdonság neve a következővel $
kezdődik: , akkor IoT Hub először megkeresi a rendszertulajdonságokban, és ha nem található, akkor az alkalmazás tulajdonságai között keres rá. Az alábbi példák bemutatják, hogyan kérdezhet le rendszertulajdonságokat és alkalmazástulajdonságokat.
A contentEncoding rendszertulajdonság lekérdezése:
$contentEncoding = 'UTF-8'
A processingPath alkalmazástulajdonság lekérdezése:
processingPath = 'hot'
A lekérdezések kombinálásához logikai kifejezéseket és függvényeket használhat:
$contentEncoding = 'UTF-8' AND processingPath = 'hot'
A támogatott operátorok és függvények teljes listáját a IoT Hub ikereszközök, feladatok és üzenet-útválasztás lekérdezési nyelvénekkifejezés és feltételek szakaszában találja.
Lekérdezés üzenettörzs alapján
Az üzenettörzs lekérdezésének engedélyezéséhez az üzenetnek JSON formátumban kell lennie, és UTF-8, UTF-16 vagy UTF-32 formátumban kell kódolnia. A contentType
rendszertulajdonságnak a következőnek kell lennie application/JSON
: . A contentEncoding
rendszertulajdonságnak az adott rendszertulajdonság által támogatott UTF-kódolási értékek egyikének kell lennie. Ha ezek a rendszertulajdonságok nincsenek megadva, IoT Hub nem értékeli ki a lekérdezési kifejezést az üzenettörzsben.
Az alábbi JavaScript-példa bemutatja, hogyan hozhat létre egy megfelelően formázott és kódolt JSON-törzset tartalmazó üzenetet:
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);
});
A C# üzenetkódolási mintáját a Microsoft Azure IoT SDK for .NET-ben elérhető HubRoutingSample című témakörben találja. Ez a minta ugyanaz, amelyet az Üzenet útválasztása oktatóanyagban használt. A Program.cs fájlnak van egy nevű ReadOneRowFromFile
metódusa is, amely beolvassa az egyik kódolt fájlt, dekódolja, majd ASCII-ként írja vissza, hogy elolvashassa.
Üzenettörzs lekérdezési kifejezései
Az üzenettörzsben lévő lekérdezéseket előtaggal $body
kell ellátva megadni. A lekérdezési kifejezésben használhat törzshivatkozást, törzstömbhivatkozást vagy több törzshivatkozást. A lekérdezési kifejezés egy törzshivatkozást is kombinálhat az üzenetrendszer tulajdonságainak hivatkozásával vagy az üzenetalkalmazás tulajdonságainak referenciájával. Az alábbi példák például az összes érvényes lekérdezési kifejezés:
$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'
Lekérdezéseket és függvényeket csak a törzshivatkozás tulajdonságain futtathat. A teljes törzshivatkozáson nem futtathat lekérdezéseket vagy függvényeket. A következő lekérdezés például nem támogatott, és visszaadja a következőt undefined
:
$body[0] = 'Feb'
Az ikerértesítés hasznos adatainak a megváltozott adatok alapján történő szűréséhez futtassa a lekérdezést az üzenettörzsben. Ha például szűrni szeretne, ha a kívánt tulajdonság megváltozik sendFrequency
, és az érték nagyobb, mint 10:
$body.properties.desired.telemetryConfig.sendFrequency > 10
A tulajdonságváltozást tartalmazó üzenetek szűréséhez a tulajdonság értékétől függetlenül használhatja a is_defined()
függvényt (ha az érték primitív típus):
is_defined($body.properties.desired.telemetryConfig.sendFrequency)
Lekérdezés eszköz vagy modul ikereszköze alapján
Az üzenet-útválasztás lehetővé teszi az ikereszköz vagy modul ikercímkéinek és tulajdonságainak lekérdezését, amelyek JSON-objektumok. Az alábbi minta egy ikereszközt mutat be címkékkel és tulajdonságokkal:
{
"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
}
}
}
Megjegyzés
A modulok nem öröklik az ikercímkéket a megfelelő eszközeikről. Iker lekérdezések az eszközmodulokból (például IoT Edge modulokból) származó üzenetekre, és nem a megfelelő ikereszközre.
Iker lekérdezési kifejezések
Az ikereszközre vagy modul ikerpéldányra vonatkozó lekérdezéseket előtaggal $twin
kell megadni. A lekérdezési kifejezés ikercímkét vagy tulajdonsághivatkozást is kombinálhat törzshivatkozással, üzenetrendszer-tulajdonságok referenciájával vagy üzenetalkalmazás tulajdonságainak hivatkozásával. Javasoljuk, hogy egyedi neveket használjunk címkékben és tulajdonságokban, mert a lekérdezés nem megkülönbözteti a kis- és nagybetűket. Ez a javaslat az ikereszközökre és a modulikrekre egyaránt vonatkozik. Azt is javasoljuk, hogy ne használjon twin
, $twin
, , body
vagy $body
tulajdonságnévként. Az alábbi példák például az összes érvényes lekérdezési kifejezés:
$twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'
$twin.tags.deploymentLocation.floor = 1
Korlátozások
Az útválasztási lekérdezések nem támogatják a whitespace vagy a következő karakterek használatát a tulajdonságnevekben, az üzenettörzsben vagy az eszköz/modul ikerútvonalában: ()<>@,;:\"/?={}
.
Következő lépések
- Tudnivalók az üzenetek útválasztásáról.
- Próbálja ki az üzenet-útválasztási oktatóanyagot.