IoT-központ üzenet-útválasztásának lekérdezési szintaxisa

Cikk
06/13/2024

Az üzenet-útválasztás lehetővé teszi a felhasználók számára, hogy különböző adattípusokat, köztük 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ítják. Gazdag lekérdezéseket is alkalmazhat ezekre az adatokra, mielőtt útválasztással megkaphatja az Önnek fontos adatokat. Ez a cikk az IoT Hub üzenet-útválasztási lekérdezési nyelvét ismerteti, és néhány gyakori lekérdezési mintát tartalmaz.

Feljegyzé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-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.

Az üzenet-útválasztással lekérdezheti az üzenet tulajdonságait és üzenettörzsét, valamint az ikereszköz-címkéket és az ikereszköz-tulajdonságokat. Ha az üzenet törzse 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 nem lesznek átirányítva. Ha a kifejezés null vagy nem definiált értéket ad vissza, logikai hamis értékként lesz kezelve, és hibát generál az IoT Hub erőforrásnaplóiban. A lekérdezés szintaxisának helyesnek kell lennie az útvonal mentéséhez és kiértékeléséhez.

Lekérdezés üzenettulajdonságok alapján

Az IoT Hub egy közös formátumot határoz meg az összes eszközről a felhőbe irányuló üzenetküldéshez a protokollok közötti együttműködéshez. Az IoT Hub az üzenet következő JSON-ábrázolását feltételezi. A rendszer minden felhasználóhoz hozzáadja a rendszertulajdonságokat, és azonosítja 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 az IoT Hub-eszközök közötti üzenetküldés nem megkülönbözteti a kis- és nagybetűket. Ha például több azonos nevű tulajdonsággal rendelkezik, az 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	Leírás
contentType	húr	A felhasználó megadja az üzenet tartalomtípusát. Az üzenettörzs lekérdezésének engedélyezéséhez ezt az értéket a következőre kell állítani `application/JSON`: .
contentEncoding	húr	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`következők`UTF-8`: és`UTF-32`.
iothub-connection-device-id	húr	Ezt az értéket az 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	húr	Ezt az értéket az IoT Hub állítja be, és azonosítja a peremmodul azonosítóját. A lekérdezéshez használja a következőt `$connectionModuleId`: .
iothub-enqueuedtime	húr	Ezt az értéket az IoT Hub állítja be, és az üzenet utc-ben történő lekérdezésének tényleges időpontját jelöli. A lekérdezéshez használja a következőt `$enqueuedTime`: .
dt-dataschema	húr	Ezt az értéket az IoT Hub állítja be az eszközről a felhőbe irányuló üzeneteken. 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	húr	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`: .

A többi elérhető rendszertulajdonságról további információt az IoT Hub-üzenetek létrehozása és olvasása című témakörben talál.

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ágaira vonatkozó lekérdezésnek előtaggal kell rendelkeznie a $ szimbólummal. Az alkalmazástulajdonságokra vonatkozó lekérdezések a nevükkel érhetők el, és nem szabad a szimbólummal előtaggal rendelkezniük $. Ha egy alkalmazástulajdonság neve a következővel $kezdődik, akkor az IoT Hub először a rendszertulajdonságokban keresi meg, é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 rendszertulajdonság contentEncoding lekérdezése:

$contentEncoding = 'UTF-8'

Az alkalmazástulajdonság processingPath 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 az IoT Hub lekérdezési nyelvének kifejezési és feltételek szakaszában találja az ikereszközökhöz, a feladatokhoz és az üzenet-útválasztáshoz.

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, az IoT Hub nem értékeli ki a lekérdezési kifejezést az üzenet törzsében.

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áért lásd a .NET-hez készült Microsoft Azure IoT SDK-ban található HubRoutingSample-et . Ez a minta ugyanaz, amelyet az Üzenet útválasztása oktatóanyagban használt. A Program.cs fájlnak van egy metódusa ReadOneRowFromFileis, 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 $bodykell megadni. A lekérdezési kifejezésben használhat törzshivatkozást, törzstömb-hivatkozást vagy több törzshivatkozást. A lekérdezési kifejezés kombinálhatja a törzshivatkozásokat az üzenetrendszer tulajdonságaira vagy az üzenetalkalmazás tulajdonságaira vonatkozó hivatkozással is. A következő 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'

Ha egy ikerértesítés hasznos adatát szeretné szűrni a megváltozott adatok alapján, futtassa a lekérdezést az üzenettörzsben. Szűrhet például, 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 egy 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ék és -tulajdonságok 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 
        } 
    } 
}

Feljegyzé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öz vagy modul ikereszközén lévő lekérdezéseket előtaggal $twinkell megadni. A lekérdezési kifejezés kombinálhat egy ikercímkét vagy tulajdonsághivatkozást egy törzshivatkozással, egy üzenetrendszer tulajdonságaira vonatkozó hivatkozással vagy egy üzenetalkalmazás tulajdonságaira vonatkozó hivatkozással. 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, $twinvagy $body bodytulajdonságnévként. A következő 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 szóköz vagy az alábbi 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 üzenet-útválasztásról.
Próbálja ki az üzenet-útválasztási oktatóanyagot.

Megosztás a következőn keresztül: