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

IoT Hub üzenet-útválasztási lekérdezés szintaxisa

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 útvonalakat kijelölve megkapja a Ön számára 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.

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 kapcsolatban további információkért lásd Válassza ki a megoldása számára megfelelő IoT Hub-szintet és -méretet.

Az üzenet útválasztás lehetővé teszi az üzenet tulajdonságainak és az üzenettörzs lekérdezését, valamint az eszköz iker címkék és eszköz iker tulajdonságok lekérdezését. 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ékre értékel, logikai hamis értékként kezeli, és hibát okoz az IoT Hub útválasztási 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:

Ingatlan típus Leírás
tartalomtípus szál/zsinó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: .
tartalomkódolás szál/zsinó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 UTF-8, UTF-16 és UTF-32.
iothub-csatlakozási-eszköz-azonosító szál/zsinór Az IoT Hub beállítja ezt az értéket, amely azonosítja az eszköz azonosítóját. A lekérdezéshez használja a következőt $connectionDeviceId: .
iothub-csatlakozás-modul-azonosító szál/zsinór Az IoT Hub beállítja ezt az értéket, amely azonosítja a peremmodul azonosítóját. A lekérdezéshez használja a következőt $connectionModuleId: .
iothub-enqueuedtime szál/zsinór Az IoT Hub beállítja ezt az értéket, amely az üzenet sorba állításának tényleges időpontját jelöli UTC-ben. A lekérdezéshez használja a következőt $enqueuedTime: .
dt-adatséma szál/zsinór Az IoT Hub ezt az értéket az eszközről a felhőbe irányuló üzenetekre á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: .
téma dt szál/zsinó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 előtagként használniuk a szimbólumot $. 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 "feldolgozási útvonal" 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ések és feltételek szakaszában találja az ikereszközökhöz és modulokhoz, feladatokhoz és ü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ási 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és elé $bodyelőtagot szükséges tenni. 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 lehet lekérdezéseket vagy függvényeket futtatni. 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. Például akkor szűrjünk, ha a sendFrequency kívánt tulajdonságváltozása bekövetkezik, é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 eszköziker vagy moduliker cí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 
        } 
    } 
}

Megjegyzés:

A modulok nem öröklik az ikercímkéket a megfelelő eszközeikről. Kettős lekérdezések az eszközmodulokból (például IoT Edge-modulokból) származó üzenetek esetében a modul duplikátumot, és nem a megfelelő eszköz duplikátumot célozzák meg.

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, $twin, body vagy $body tulajdonsá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