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

Cikk
03/18/2023

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ének kifejezé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ű ReadOneRowFromFilemetó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 $bodykell 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 $twinkell 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, , bodyvagy $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.

Share via