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

Článek
06/13/2024

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čat zařízení do různých koncových bodů. Na tato data můžete také použít bohaté dotazy, než je nasměrujete, abyste získali data, která jsou pro vás důležitá. Tento článek popisuje dotazovací jazyk směrování zpráv ioT Hubu 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 úrovních Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu 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čete zařízení a vlastnosti dvojčete zařízení. Pokud text zprávy není ve formátu JSON, směrování zpráv může i nadále směrovat zprávu, ale dotazy se nedají použít v textu zprávy. 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 hodnota null nebo nedefinovaná hodnota, považuje se za logickou hodnotu false a vygeneruje chybu v protokolech prostředků ioT Hubu. 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 všechny zasílání zpráv typu zařízení-cloud pro interoperabilitu napříč protokoly. IoT Hub předpokládá následující reprezentaci zprávy ve formátu JSON. Systémové vlastnosti se přidají pro všechny uživatele a identifikují obsah zprávy. Uživatelé mohou do zprávy selektivně přidávat vlastnosti aplikace. Doporučujeme používat jedinečné názvy vlastností, protože zasílání zpráv typu zařízení-cloud ve službě IoT Hub nerozlišuje malá a velká písmena. Pokud například máte více vlastností se stejným názvem, IoT Hub odešle jenom jednu z těchto 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 popsané v následující tabulce:

Vlastnost	Type	Popis
contentType	string	Uživatel určuje typ obsahu zprávy. Chcete-li povolit dotazování na text zprávy, měla by být tato hodnota nastavena na `application/JSON`hodnotu .
contentEncoding	string	Uživatel určuje typ kódování zprávy. Pokud je vlastnost contentType nastavena na `application/JSON`, pak povolené hodnoty jsou `UTF-8`, `UTF-16`a `UTF-32`.
iothub-connection-device-id	string	Tato hodnota je nastavena službou IoT Hub a identifikuje ID zařízení. K dotazování použijte `$connectionDeviceId`.
iothub-connection-module-id	string	Tato hodnota je nastavena službou IoT Hub a identifikuje ID hraničního modulu. K dotazování použijte `$connectionModuleId`.
iothub-enqueuedtime	string	Tato hodnota je nastavena službou IoT Hub a představuje skutečný čas zařazení zprávy do fronty ve standardu UTC. K dotazování použijte `$enqueuedTime`.
dt-dataschema	string	Tato hodnota je nastavena službou IoT Hub ve zprávách typu zařízení-cloud. Obsahuje ID modelu zařízení nastavené v připojení zařízení. K dotazování použijte `$dt-dataschema`.
dt-subject	string	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 Vytváření a čtení zpráv ioT Hubu.

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 vlastnosti systému zpráv musí být předponou symbolu $ . Dotazy na vlastnosti aplikace jsou přístupné s jejich názvem a neměly by být předponou symbolu $. Pokud název vlastnosti aplikace začíná $, Služba IoT Hub ji nejprve vyhledá ve vlastnostech systému a pokud se nenajde, vyhledá ji ve vlastnostech aplikace. Následující příklady ukazují, jak dotazovat na vlastnosti systému a vlastnosti aplikace.

Dotazování na obsah systémové vlastnosti:

$contentEncoding = 'UTF-8'

Dotazování 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 dotazovacího jazyka služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

Dotaz založený na textu zprávy

Pokud chcete povolit dotazování na text zprávy, měla by být zpráva ve formátu JSON a zakódovaná ve formátu UTF-8, UTF-16 nebo UTF-32. Vlastnost contentType systému musí být application/JSON. Systémová contentEncoding vlastnost musí být jednou 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 kó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 hubRoutingSample poskytované v sadě Microsoft Azure IoT SDK pro .NET. Tato ukázka je stejná jako v kurzu Směrování zpráv. Soubor Program.cs má 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 čí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 matici těla nebo více odkazů na text. Výraz dotazu může také kombinovat základní odkaz s odkazem na systémové vlastnosti zprávy nebo 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 referenčním textu. Dotazy ani funkce nemůžete spouštět v celém odkazu na tělo. Například následující dotaz není podporován a vrací: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ž se změní sendFrequency požadovaná vlastnost a hodnota je větší než 10:

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

Chcete-li 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)

Dotazování 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 dvojčete 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 příslušných zařízení. Dotazy dvojčete na zprávy pocházející z modulů zařízení (například z modulů IoT Edge) se dotazují na dvojče modulu, nikoli na odpovídající dvojče zařízení.

Výrazy dotazu dvojčete

Dotaz na dvojče zařízení nebo dvojče modulu musí mít předponu $twin. Výraz dotazu může také kombinovat 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. Doporučujeme použít jedinečné názvy ve značkách a vlastnostech, protože dotaz nerozlišuje malá a velká písmena. Toto doporučení platí pro dvojčata zařízení i dvojčata modulů. Také doporučujeme, abyste se vyhnuli použití twin, $twin, bodynebo $body jako názvy vlastností. 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ý z následujících znaků v názvech vlastností, cestu textu zprávy nebo cestu dvojčete zařízení/modulu: ()<>@,;:\"/?={}

Další kroky

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

Sdílet prostřednictvím