Syntaxe dotazu směrování zpráv IoT Hubu

Článek
03/18/2023

Směrování zpráv umožňuje uživatelům směrovat různé datové typy, včetně zpráv telemetrie zařízení, událostí životního cyklu zařízení a událostí změn dvojčete zařízení, do různých koncových bodů. Na tato data můžete také použít bohaté dotazy, než je směrujete, aby přijímala data, která jsou pro vás důležitá. Tento článek popisuje IoT Hub dotazovací jazyk směrování zpráv a poskytuje některé běžné vzory dotazů.

Poznámka

Některé funkce uvedené v tomto článku, jako je zasílání zpráv z cloudu do zařízení, dvojčata zařízení a správa zařízení, jsou k dispozici ve službě IoT Hub pouze na úrovni Standard. Další informace o IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné IoT Hub úrovně pro vaše řešení.

Směrování zpráv umožňuje dotazovat se na vlastnosti zprávy a text zprávy a také na značky dvojčat zařízení a vlastnosti dvojčat zařízení. Pokud text zprávy není ve formátu JSON, směrování zpráv i tak může zprávu směrovat, ale v textu zprávy se nedají použít dotazy. Dotazy jsou popsány jako logické výrazy, kde pokud je pravda, dotaz uspěje a směruje všechna příchozí data; jinak dotaz selže a příchozí data se nesměrují. Pokud se výraz vyhodnotí jako null nebo nedefinovaná hodnota, považuje se za logickou hodnotu false a vygeneruje chybu v IoT Hub směruje protokoly prostředků. Syntaxe dotazu musí být správná, aby se trasa uložila a vyhodnotila.

Dotaz na základě vlastností zprávy

IoT Hub definuje společný formát pro zasílání zpráv mezi zařízeními a cloudem pro interoperabilitu mezi protokoly. IoT Hub předpokládá následující reprezentaci zprávy ve formátu JSON. Systémové vlastnosti jsou přidány pro všechny uživatele a identifikují obsah zprávy. Uživatelé mohou do zprávy selektivně přidat vlastnosti aplikace. Doporučujeme používat jedinečné názvy vlastností, protože IoT Hub zasílání zpráv ze zařízení do cloudu nerozlišuje velká a malá písmena. Pokud máte například více vlastností se stejným názvem, IoT Hub odešle pouze jednu z vlastností.

{ 
  "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}}" 
  } 
}

Systémové vlastnosti

Systémové vlastnosti pomáhají identifikovat obsah a zdroj zpráv, z nichž některé jsou popsány v následující tabulce:

Vlastnost	Typ	Description
Contenttype	řetězec	Uživatel určuje typ obsahu zprávy. Pokud chcete povolit dotazování na text zprávy, měla by být tato hodnota nastavená na `application/JSON`.
obsahEncoding	řetězec	Uživatel určuje typ kódování zprávy. Pokud je vlastnost contentType nastavená na `application/JSON`, povolené hodnoty jsou `UTF-8`, `UTF-16`a `UTF-32`.
iothub-connection-device-id	řetězec	Tato hodnota se nastavuje IoT Hub a identifikuje ID zařízení. K dotazování použijte `$connectionDeviceId`.
iothub-connection-module-id	řetězec	Tato hodnota se nastavuje IoT Hub a identifikuje ID modulu Edge. K dotazování použijte `$connectionModuleId`.
iothub-enqueuedtime	řetězec	Tato hodnota je nastavena IoT Hub a představuje skutečný čas zařazení zprávy do fronty v UTC. K dotazování použijte `$enqueuedTime`.
dt-dataschema	řetězec	Tato hodnota se nastavuje IoT Hub ve zprávách zařízení-cloud. Obsahuje ID modelu zařízení nastavené v připojení zařízení. K dotazování použijte `$dt-dataschema`.
dt-subject	řetězec	Název komponenty, která odesílá zprávy typu zařízení-cloud. K dotazování použijte `$dt-subject`.

Další informace o dalších dostupných systémových vlastnostech najdete v tématu Vytvoření a čtení IoT Hub zpráv.

Vlastnosti aplikace

Vlastnosti aplikace jsou uživatelem definované řetězce, které lze přidat do zprávy. Tato pole jsou volitelná.

Výrazy dotazu vlastností zprávy

Dotaz na systémové vlastnosti zpráv musí mít předponu symbolu $ . K dotazům na vlastnosti aplikace se přistupuje s jejich názvem a nemělo by být předponou symbol.$ Pokud název vlastnosti aplikace začíná $na , IoT Hub ho nejprve vyhledá v systémových vlastnostech, a pokud ho nenajde, vyhledá ho ve vlastnostech aplikace. Následující příklady ukazují, jak se dotazovat na systémové vlastnosti a vlastnosti aplikace.

Dotaz na vlastnost systému contentEncoding:

$contentEncoding = 'UTF-8'

Dotaz na vlastnost aplikace processingPath:

processingPath = 'hot'

Ke kombinování těchto dotazů můžete použít logické výrazy a funkce:

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Úplný seznam podporovaných operátorů a funkcí najdete v části výrazů a podmínek IoT Hub dotazovacího jazyka pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

Dotaz na základě textu zprávy

Pokud chcete povolit dotazování na text zprávy, musí být zpráva ve formátu JSON a zakódovaná ve formátu UTF-8, UTF-16 nebo UTF-32. Systémová contentType vlastnost musí být application/JSON. Systémová contentEncoding vlastnost musí být jedna z hodnot kódování UTF podporovaných danou systémovou vlastností. Pokud tyto systémové vlastnosti nejsou zadané, IoT Hub nevyhodnotí výraz dotazu v textu zprávy.

Následující příklad JavaScriptu ukazuje, jak vytvořit zprávu se správně vytvořeným a zakódovaným textem JSON:

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);
});

Ukázku kódování zpráv v jazyce C# najdete v ukázce HubRoutingSample v sadě Microsoft Azure IoT SDK pro .NET. Tato ukázka je stejná jako v kurzu Směrování zpráv. Soubor Program.cs obsahuje také metodu s názvem ReadOneRowFromFile, která čte jeden z zakódovaných souborů, dekóduje ho a zapisuje zpět jako ASCII, abyste ho mohli přečíst.

Výrazy dotazu textu zprávy

Dotaz na text zprávy musí mít předponu $body. Ve výrazu dotazu můžete použít odkaz na tělo, odkaz na pole těla nebo více odkazů na tělo. Výraz dotazu může také zkombinovat základní odkaz s odkazem na systémové vlastnosti zprávy nebo s odkazem na vlastnosti aplikace zprávy. Například následující příklady jsou všechny platné výrazy dotazu:

$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'

Dotazy a funkce můžete spouštět pouze u vlastností v odkazu na text. Dotazy nebo funkce nemůžete spouštět v celém odkazu na tělo. Například následující dotaz není podporovaný a vrátí undefined:

$body[0] = 'Feb'

Pokud chcete filtrovat datovou část oznámení dvojčete podle toho, co se změnilo, spusťte dotaz v textu zprávy. Pokud chcete například filtrovat, když dojde ke sendFrequency změně požadované vlastnosti a hodnota je větší než 10:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Pokud chcete filtrovat zprávy, které obsahují změnu vlastnosti, bez ohledu na hodnotu vlastnosti, můžete použít is_defined() funkci (pokud je hodnota primitivním typem):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Dotaz na základě dvojčete zařízení nebo modulu

Směrování zpráv umožňuje dotazovat se na značky a vlastnosti dvojčete zařízení nebo modulu , což jsou objekty JSON. Následující ukázka znázorňuje dvojče zařízení se značkami a vlastnostmi:

{
    "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 
        } 
    } 
}

Poznámka

Moduly nedědí značky dvojčat z odpovídajících zařízení. Dotazy na dvojčata pro zprávy pocházející z modulů zařízení (například z modulů IoT Edge) se dotazují na dvojče modulu, a ne na odpovídající dvojče zařízení.

Výrazy dotazů dvojčat

Dotaz na dvojče zařízení nebo dvojčete modulu musí mít předponu $twin. Výraz dotazu může také zkombinovat značku dvojčete nebo odkaz na vlastnost s odkazem na tělo, odkazem na systémové vlastnosti zprávy nebo odkazem na vlastnosti aplikace zprávy. Ve značkách a vlastnostech doporučujeme používat jedinečné názvy, protože v dotazu se nerozličují malá a velká písmena. Toto doporučení platí pro dvojčata zařízení i dvojčata modulů. Doporučujeme také, abyste jako názvy vlastností nepoužívat twin, $twinbody, nebo $body . Například následující příklady jsou všechny platné výrazy dotazu:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Omezení

Dotazy směrování nepodporují použití prázdných znaků ani žádného z následujících znaků v názvech vlastností, cestě k textu zprávy nebo cestě k dvojčeti zařízení/modulu: ()<>@,;:\"/?={}.

Další kroky

Přečtěte si o směrování zpráv.
Vyzkoušejte kurz směrování zpráv.