Sdílet prostřednictvím

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

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 Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

Směrování zpráv umožňuje dotazovat se na vlastnosti zprávy a tělo zprávy a také na značky digitálního dvojčete zařízení a vlastnosti digitálního 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á, považuje se za logickou hodnotu false a vygeneruje chybu v protokolech směrování prostředků služby IoT Hub. 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.

Poznámka:

Doporučujeme používat jedinečné názvy vlastností, protože zasílání zpráv z zařízení do cloudu skrze IoT Hub nerozlišuje malá a velká písmena. Pokud máte například 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 Typ Popis
typ obsahu řetězec 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/JSONhodnotu .
kódování obsahu řetězec 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-16a UTF-32.
iothub-připojení-id-zařízení řetězec IoT Hub nastaví tuto hodnotu, která identifikuje ID zařízení. K dotazování použijte $connectionDeviceId.
Identifikátor modulu připojení iothub řetězec IoT Hub nastaví tuto hodnotu, která identifikuje ID hraničního modulu. K dotazování použijte $connectionModuleId.
iothub-enqueuedtime řetězec IoT Hub nastaví tuto hodnotu, která představuje uskutečněný čas zařazení zprávy do fronty v UTC. K dotazování použijte $enqueuedTime.
dt-dataschema řetězec IoT Hub nastavuje tuto hodnotu pro zprávy z zařízení do cloudu. Obsahuje ID modelu zařízení nastavené v připojení zařízení. K dotazování použijte $dt-dataschema.
dt-předmět řetězec Název komponenty, která odesílá zprávy z zařízení do cloudu. 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 pro vlastnosti 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 není nalezena, vyhledá ji ve vlastnostech aplikace. Následující příklady ukazují, jak dotazovat na vlastnosti systému a vlastnosti aplikace.

Pro dotazování na systémovou vlastnost contentEncoding:

$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ýrazy a podmínkydotazovací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 nevyhodnocuje 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 pro dotaz na text 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é 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 na celé tělové referenci. 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 tělu zprávy. Například, chcete-li filtrovat, když se požadovaná vlastnost na sendFrequency změní 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 ze svých odpovídajících zařízení. Dotazy pro dvojčata týkající se zpráv pocházejících z modulů zařízení (například z modulů IoT Edge) se zaměřují na dvojče modulu, nikoli na odpovídající dvojče zařízení.

Výrazy dotazu dvojníků

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 aplikační vlastnosti zprávy. 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

Poznámka:

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ů. Měli byste se také vyhnout použití twin, $twin, bodynebo $body jako názvy vlastností.

Omezení

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

Další kroky

  • Last updated on