Vytvoření a čtení zpráv IoT Hubu
Pro podporu interoperability mezi protokoly ioT Hub definuje společnou sadu funkcí zasílání zpráv, které jsou k dispozici ve všech protokolech přístupných zařízením. Tyto funkce je možné použít ve zprávách typu zařízení-cloud i ve zprávách typu cloud-zařízení.
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í.
IoT Hub implementuje zasílání zpráv typu zařízení-cloud pomocí vzoru streamování zpráv. Zprávy ioT Hubu typu zařízení-cloud jsou spíše podobné událostem služby Event Hubs než zprávy služby Service Bus v tom, že existuje velký objem událostí procházejících službou, kterou může číst více čtenářů.
Zpráva ioT Hubu se skládá z:
Předem stanovená sada vlastností systému, jak je popsáno dále v tomto článku.
Sada vlastností aplikace. Slovník vlastností řetězce, ke kterým může aplikace definovat a přistupovat, aniž by bylo nutné deserializovat text zprávy. IoT Hub tyto vlastnosti nikdy neupravuje.
Text zprávy, který může být libovolný typ dat.
Každý protokol zařízení implementuje vlastnosti nastavení různými způsoby. Další informace najdete v průvodci pro vývojáře v průvodci protokolem MQTT a průvodce protokolem AMQP.
Při odesílání zpráv typu zařízení-cloud pomocí protokolu HTTPS nebo odesílání zpráv typu cloud-zařízení mohou názvy a hodnoty vlastností obsahovat pouze alfanumerické znaky ASCII, plus ! # $ % & ' * + - . ^ _ ` | ~ .
Zasílání zpráv ze zařízení do cloudu se službou IoT Hub má následující charakteristiky:
Zprávy typu zařízení-cloud jsou trvalé a uchovávají se ve výchozím koncovém bodu zpráv a událostí služby IoT Hub po dobu až sedmi dnů.
Zprávy typu zařízení-cloud můžou být maximálně 256 kB a dají se seskupit do dávek za účelem optimalizace odesílání. Dávky můžou mít maximálně 256 kB.
IoT Hub neumožňuje libovolné dělení. Zprávy typu zařízení-cloud jsou rozdělené na oddíly na základě jejich původního ID zařízení.
Jak je vysvětleno v tématu Řízení přístupu ke službě IoT Hub, Služba IoT Hub umožňuje ověřování podle zařízení a řízení přístupu.
Zprávy můžete razítekovat informacemi, které přejdou do vlastností aplikace. Další informace najdete v tématu rozšiřování zpráv.
Poznámka:
Každý protokol IoT Hubu poskytuje vlastnost typu obsahu zprávy, která se respektuje při směrování dat do vlastních koncových bodů. Pokud chcete, aby data správně zpracovala v cíli (například JSON, který se považuje za parsovatelný řetězec místo binárních dat s kódováním Base64), zadejte odpovídající typ obsahu a znakovou sadu pro zprávu.
Chcete-li použít text zprávy ve směrovacím dotazu služby IoT Hub, zadejte platný objekt JSON zprávy a nastavte vlastnost typu obsahu zprávy na application/json;charset=utf-8.
Následující příklad ukazuje platný směrovatelný text zprávy:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Systémové vlastnosti zpráv typu zařízení-cloud
| Vlastnost | Popis | Nastavitelné uživatelem? | Klíčové slovo pro dotaz směrování |
|---|---|---|---|
| message-id | Identifikátor uživatelem nastavený pro zprávu použitou pro vzory žádosti a odpovědi. Formát: Řetězec rozlišující malá a velká písmena (maximálně 128 znaků dlouhý) 7bitové alfanumerické znaky ASCII plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Ano | messageId |
| iothub-enqueuedtime | Služba IoT Hub přijala zprávu typu zařízení-cloud a čas. | No | enqueuedTime |
| ID uživatele | ID použité k určení původu zpráv. | Ano | userId |
| iothub-connection-device-id | ID nastavené službou IoT Hub na zprávách typu zařízení-cloud Obsahuje ID zařízení , které zprávu odeslalo. | No | connectionDeviceId |
| iothub-connection-module-id | ID nastavené službou IoT Hub na zprávách typu zařízení-cloud Obsahuje id modulu zařízení, které zprávu odeslalo. | No | connectionModuleId |
| iothub-connection-auth-generation-id | ID nastavené službou IoT Hub na zprávách typu zařízení-cloud Obsahuje connectionDeviceGenerationId (podle vlastností identity zařízení) zařízení, které zprávu odeslalo. | No | connectionDeviceGenerationId |
| iothub-connection-auth-method | Metoda ověřování nastavená službou IoT Hub ve zprávách typu zařízení-cloud Tato vlastnost obsahuje informace o metodě ověřování použité k ověření zařízení odesílajícího zprávu. | No | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Umožňuje zařízení odesílat čas vytvoření události při odesílání dat v dávce. | Ano | creation-time-utc |
| iothub-creation-time-utc | Umožňuje zařízení odesílat čas vytvoření události při odesílání jedné zprávy najednou. | Ano | creation-time-utc |
| dt-dataschema | Tato hodnota je nastavena službou IoT Hub na zprávách typu zařízení-cloud. Obsahuje ID modelu zařízení nastavené v připojení zařízení. | No | $dt-dataschema |
| dt-subject | Název komponenty, která odesílá zprávy typu zařízení-cloud. | Ano | předmět $dt |
Vlastnosti aplikace zpráv typu zařízení-cloud
Běžným použitím vlastností aplikace je odeslání časového razítka ze zařízení pomocí iothub-creation-time-utc vlastnosti k zaznamenání, kdy zařízení zprávu odeslalo. Formát tohoto časového razítka musí být UTC bez informací o časovém pásmu. Je například 2021-04-21T11:30:16Z platný, ale 2021-04-21T11:30:16-07:00 je neplatný.
{
"applicationId":"00001111-aaaa-2222-bbbb-3333cccc4444",
"messageSource":"telemetry",
"deviceId":"sample-device-01",
"schema":"default@v1",
"templateId":"urn:modelDefinition:mkuyqxzgea:e14m1ukpn",
"enqueuedTime":"2021-01-29T16:45:39.143Z",
"telemetry":{
"temperature":8.341033560421833
},
"messageProperties":{
"iothub-creation-time-utc":"2021-01-29T16:45:39.021Z"
},
"enrichments":{}
}
Systémové vlastnosti zpráv typu cloud-zařízení
| Vlastnost | Popis | Nastavitelné uživatelem? |
|---|---|---|
| message-id | Identifikátor uživatelem nastavený pro zprávu použitou pro vzory žádosti a odpovědi. Formát: Řetězec rozlišující malá a velká písmena (maximálně 128 znaků dlouhý) 7bitové alfanumerické znaky ASCII plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Ano |
| pořadové číslo | Číslo (jedinečné na frontu zařízení) přiřazené službou IoT Hub ke každé zprávě typu cloud-zařízení | No |
| na | Cíl zadaný ve zprávách typu Cloud-zařízení . | No |
| absolutní doba vypršení platnosti | Datum a čas vypršení platnosti zprávy | Ano |
| ID korelace | Vlastnost řetězce ve zprávě odpovědi, která obvykle obsahuje MessageId požadavku ve vzorech odpovědí na požadavek. | Ano |
| ID uživatele | ID použité k určení původu zpráv. Když ioT Hub vygeneruje zprávy, ID uživatele je název centra IoT. | Ano |
| iothub-ack | Generátor zpráv zpětné vazby. Tato vlastnost se používá ve zprávách typu cloud-zařízení k vyžádání ioT Hubu, aby vygenerovala zprávy zpětné vazby v důsledku spotřeby zprávy zařízením. Možné hodnoty: žádné (výchozí): nevygeneruje se žádná zpráva zpětné vazby, pozitivní: pokud byla zpráva dokončena, negativní: obdrží zprávu zpětné vazby, pokud vypršela platnost zprávy (nebo byl dosažen maximální počet doručení), aniž by zařízení dokončilo, nebo úplné: kladné i záporné. | Ano |
Názvy systémových vlastností
Názvy systémových vlastností se liší v závislosti na koncovém bodu, do kterého se zprávy směrují.
| Název systémové vlastnosti | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| ID zprávy | message-id | messageId | MessageId | message-id |
| ID uživatele | ID uživatele | userId | ID uživatele | ID uživatele |
| ID zařízení připojení | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| ID modulu připojení | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| ID generování ověřování připojení | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Metoda ověřování připojení | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | content-type | contentType | ContentType | iothub-content-type |
| contentEncoding | kódování obsahu | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | – | iothub-enqueuedtime |
| CorrelationId | ID korelace | correlationId | CorrelationId | ID korelace |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Velikost zprávy
IoT Hub měří velikost zpráv bez ohledu na skutečnou datovou část, která je nezávislá na protokolu. Velikost v bajtech se vypočítá jako součet následujících hodnot:
- Velikost těla v bajtech.
- Velikost v bajtech všech hodnot vlastností systému zpráv.
- Velikost v bajtech všech názvů a hodnot uživatelských vlastností.
Názvy a hodnoty vlastností jsou omezeny na znaky ASCII, takže délka řetězců se rovná velikosti v bajtech.
Vlastnosti falšování identity
Aby se zabránilo falšování identity zařízení ve zprávách zařízení-cloud, IoT Hub označí všechny zprávy následujícími vlastnostmi:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
První dva obsahují id zařízení a generationId původního zařízení podle vlastností identity zařízení.
Vlastnost iothub-connection-auth-method obsahuje serializovaný objekt JSON s následujícími vlastnostmi:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Další kroky
- Informace o omezeních velikosti zpráv ve službě IoT Hub najdete v tématu Kvóty a omezování služby IoT Hub.
- Informace o vytváření a čtení zpráv IoT Hubu v různých programovacích jazycích najdete v rychlých startech.
- Další informace o struktuře událostí mimo telemetrii generovaných službou IoT Hub najdete v tématu Schémata událostí mimo telemetrii služby IoT Hub.