Tworzenie i odczytywanie komunikatów usługi IoT Hub
Aby zapewnić bezproblemową współdziałanie między protokołami, usługa IoT Hub definiuje wspólny zestaw funkcji obsługi komunikatów, które są dostępne we wszystkich protokołach dostępnych dla urządzeń. Mogą one być używane zarówno w routingu komunikatów z urządzenia do chmury, jak i w komunikatach z chmury do urządzenia.
Uwaga
Niektóre funkcje wymienione w tym artykule, takie jak obsługa komunikatów w chmurze, bliźniacze reprezentacje urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.
Usługa IoT Hub implementuje przesyłanie komunikatów z urządzenia do chmury przy użyciu wzorca przesyłania strumieniowego komunikatów. Komunikaty urządzenie-chmura usługi IoT Hub są bardziej podobne do zdarzeń usługi Event Hubsniż komunikaty usługi Service Bus, w których istnieje duża liczba zdarzeń przechodzących przez usługę, która może być odczytywana przez wielu czytelników.
Komunikat usługi IoT Hub składa się z następujących elementów:
Wstępnie określony zestaw właściwości systemowych, jak pokazano poniżej.
Zestaw właściwości aplikacji. Słownik właściwości ciągu, do którego aplikacja może definiować i uzyskiwać dostęp bez konieczności deserializacji treści komunikatu. Usługa IoT Hub nigdy nie modyfikuje tych właściwości.
Treść komunikatu, która może być dowolnym typem danych.
Każdy protokół urządzenia implementuje właściwości ustawień na różne sposoby. Aby uzyskać szczegółowe informacje, zobacz powiązane przewodniki dla deweloperów MQTT i AMQP .
Nazwy właściwości i wartości mogą zawierać tylko znaki alfanumeryczne ASCII, a także {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} podczas wysyłania komunikatów z urządzenia do chmury przy użyciu protokołu HTTPS lub wysyłania komunikatów z chmury do urządzenia.
Obsługa komunikatów z urządzenia do chmury w usłudze IoT Hub ma następujące cechy:
Komunikaty z urządzenia do chmury są trwałe i przechowywane w domyślnym punkcie końcowym komunikatów/zdarzeń centrum IoT przez maksymalnie siedem dni.
Komunikaty urządzenie-chmura mogą być co najwyżej 256 KB i można je grupować w partiach w celu zoptymalizowania wysyłania. Partie mogą mieć co najwyżej 256 KB.
Usługa IoT Hub nie zezwala na dowolne partycjonowanie. Komunikaty z urządzenia do chmury są partycjonowane na podstawie ich identyfikatora deviceId pochodzącego z urządzenia.
Jak wyjaśniono w artykule Kontrola dostępu do usługi IoT Hub, usługa IoT Hub umożliwia uwierzytelnianie poszczególnych urządzeń i kontrolę dostępu.
Komunikaty można oznaczać informacjami, które przechodzą do właściwości aplikacji. Aby uzyskać więcej informacji, zobacz wzbogacanie komunikatów.
Aby uzyskać więcej informacji na temat kodowania i dekodowania komunikatów wysyłanych przy użyciu różnych protokołów, zobacz Zestawy SDK usługi Azure IoT.
Uwaga
Każdy protokół usługi IoT Hub udostępnia właściwość typu zawartości komunikatu, która jest uwzględniana podczas routingu danych do niestandardowych punktów końcowych. Aby dane były prawidłowo obsługiwane w miejscu docelowym (na przykład kod JSON jest traktowany jako ciąg do analizowania zamiast zakodowanych danych binarnych base64), musisz podać odpowiedni typ zawartości i zestaw znaków dla komunikatu.
Aby użyć treści komunikatu w zapytaniu routingu usługi IoT Hub, należy podać prawidłowy obiekt JSON dla komunikatu i ustawić właściwość typu zawartości komunikatu na application/json;charset=utf-8.
Prawidłowa, routingowa treść komunikatu może wyglądać następująco:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Właściwości systemu komunikatów usługi IoT Hub D2C
| Właściwości | opis | Tabela settable użytkownika? | Słowo kluczowe dla zapytania routingu |
|---|---|---|---|
| message-id | Identyfikator tabeli zdefiniowanej przez użytkownika dla komunikatu używanego dla wzorców żądań i odpowiedzi. Format: Ciąg uwzględniający wielkość liter (do 128 znaków długości) znaków alfanumerycznych ASCII 7-bitowych + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Tak | Messageid |
| iothub-enqueuedtime | Data i godzina odebrania komunikatu urządzenie-chmura przez usługę IoT Hub. | Nie. | enqueuedTime |
| identyfikator użytkownika | Identyfikator używany do określania źródła komunikatów. Gdy komunikaty są generowane przez usługę IoT Hub, jest ustawiona na {iot hub name}wartość . |
Tak | Identyfikator użytkownika |
| iothub-connection-device-id | Identyfikator ustawiony przez usługę IoT Hub w komunikatach urządzenie-chmura. Zawiera identyfikator deviceId urządzenia, które wysłało komunikat. | Nie. | connectionDeviceId |
| iothub-connection-module-id | Identyfikator ustawiony przez usługę IoT Hub w komunikatach urządzenie-chmura. Zawiera on identyfikator moduleId urządzenia, które wysłało komunikat. | Nie. | connectionModuleId |
| iothub-connection-auth-generation-id | Identyfikator ustawiony przez usługę IoT Hub w komunikatach urządzenie-chmura. Zawiera on parametr connectionDeviceGenerationId (zgodnie z właściwościami tożsamości urządzenia) urządzenia, które wysłało komunikat. | Nie. | connectionDeviceGenerationId |
| iothub-connection-auth-method | Metoda uwierzytelniania ustawiona przez usługę IoT Hub w komunikatach urządzenie-chmura. Ta właściwość zawiera informacje o metodzie uwierzytelniania używanej do uwierzytelniania urządzenia wysyłającego komunikat. | Nie. | connectionAuthMethod |
| iothub-app-iothub-creation-time-utc | Umożliwia urządzeniu wysyłanie czasu tworzenia zdarzeń podczas wysyłania danych w partii. | Tak | creation-time-utc |
| iothub-creation-time-utc | Umożliwia urządzeniu wysyłanie czasu tworzenia zdarzeń podczas wysyłania jednej wiadomości naraz. | Tak | creation-time-utc |
| dt-dataschema | Ta wartość jest ustawiana przez centrum IoT w komunikatach urządzenie-chmura. Zawiera identyfikator modelu urządzenia ustawiony w połączeniu urządzenia. | Nie. | $dt-dataschema |
| dt-subject | Nazwa składnika wysyłającego komunikaty z urządzenia do chmury. | Tak | temat $dt |
Właściwości aplikacji komunikatów usługi IoT Hub D2C
Typowym zastosowaniem właściwości aplikacji jest wysłanie znacznika czasu z urządzenia przy użyciu iothub-creation-time-utc właściwości w celu zarejestrowania, kiedy komunikat został wysłany przez urządzenie. Format tego znacznika czasu musi być utc bez informacji o strefie czasowej. Na przykład jest prawidłowy, 2021-04-21T11:30:16Z2021-04-21T11:30:16-07:00 jest nieprawidłowy:
{
"applicationId":"5782ed70-b703-4f13-bda3-1f5f0f5c678e",
"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":{}
}
Właściwości systemu komunikatów usługi IoT Hub C2D
| Właściwości | opis | Tabela settable użytkownika? |
|---|---|---|
| message-id | Identyfikator tabeli zdefiniowanej przez użytkownika dla komunikatu używanego dla wzorców żądań i odpowiedzi. Format: Ciąg uwzględniający wielkość liter (do 128 znaków długości) znaków alfanumerycznych ASCII 7-bitowych + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
Tak |
| sekwencja-liczba | Liczba (unikatowa dla kolejki urządzeń) przypisana przez usługę IoT Hub do każdego komunikatu z chmury do urządzenia. | Nie. |
| na wartość | Miejsce docelowe określone w komunikatach chmura-urządzenie . | Nie. |
| czas wygaśnięcia bezwzględnego | Data i godzina wygaśnięcia wiadomości. | Tak |
| identyfikator korelacji | Właściwość string w komunikacie odpowiedzi, która zazwyczaj zawiera identyfikator MessageId żądania w wzorcach odpowiedzi żądania. | Tak |
| identyfikator użytkownika | Identyfikator używany do określania źródła komunikatów. Gdy komunikaty są generowane przez usługę IoT Hub, jest ustawiona na {iot hub name}wartość . |
Tak |
| iothub-ack | Generator komunikatów zwrotnych. Ta właściwość jest używana w komunikatach chmura-urządzenie w celu żądania usługi IoT Hub wygenerowania komunikatów opinii w wyniku użycia komunikatu przez urządzenie. Możliwe wartości: brak (wartość domyślna): żaden komunikat z informacją zwrotną nie jest generowany, pozytywny: otrzymuj wiadomość zwrotną, jeśli wiadomość została ukończona, negatywna: wiadomość zwrotna, jeśli komunikat wygasł (lub osiągnięto maksymalną liczbę dostaw) bez ukończenia przez urządzenie lub pełny: zarówno pozytywny, jak i ujemny. | Tak |
Nazwy właściwości systemowych
Nazwy właściwości systemowych różnią się w zależności od punktu końcowego, do którego są kierowane komunikaty. Aby uzyskać szczegółowe informacje na temat tych nazw, zobacz poniższą tabelę.
| Nazwa właściwości systemu | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| Identyfikator komunikatu | message-id | Messageid | Messageid | message-id |
| Identyfikator użytkownika | identyfikator użytkownika | Identyfikator użytkownika | Identyfikator użytkownika | identyfikator użytkownika |
| identyfikator urządzenia Połączenie ion | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| identyfikator modułu Połączenie ion | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| identyfikator generowania uwierzytelniania Połączenie ion | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| metoda uwierzytelniania Połączenie ion | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| Contenttype | typ zawartości | Contenttype | Contenttype | iothub-content-type |
| contentEncoding | kodowanie zawartości | contentEncoding | ContentEncoding | iothub-content-encoding |
| iothub-enqueuedtime | iothub-enqueuedtime | enqueuedTime | Nie dotyczy | iothub-enqueuedtime |
| CorrelationId | identyfikator korelacji | correlationId | CorrelationId | identyfikator korelacji |
| dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema | dt-dataschema |
| dt-subject | dt-subject | dt-subject | dt-subject | dt-subject |
Rozmiar komunikatu
Usługa IoT Hub mierzy rozmiar komunikatów w sposób niezależny od protokołu, biorąc pod uwagę tylko rzeczywisty ładunek. Rozmiar w bajtach jest obliczany jako suma następujących wartości:
- Rozmiar ciała w bajtach.
- Rozmiar w bajtach wszystkich wartości właściwości systemu komunikatów.
- Rozmiar w bajtach wszystkich nazw i wartości właściwości użytkownika.
Nazwy właściwości i wartości są ograniczone do znaków ASCII, więc długość ciągów jest równa rozmiarowi w bajtach.
Właściwości ochrony przed fałszowaniem
Aby uniknąć fałszowania urządzeń w komunikatach z urządzenia do chmury, usługa IoT Hub oznacza wszystkie komunikaty o następujących właściwościach:
- iothub-connection-device-id
- iothub-connection-auth-generation-id
- iothub-connection-auth-method
Pierwsze dwa zawierają identyfikator deviceId i generationId urządzenia źródłowego zgodnie z właściwościami tożsamości urządzenia.
Właściwość iothub-connection-auth-method zawiera obiekt serializowany JSON o następujących właściwościach:
{
"scope": "{ hub | device | module }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}
Następne kroki
- Aby uzyskać informacje o limitach rozmiaru komunikatów w usłudze IoT Hub, zobacz Limity przydziału i ograniczanie przepustowości usługi IoT Hub.
- Aby dowiedzieć się, jak tworzyć i odczytywać komunikaty usługi IoT Hub w różnych językach programowania, zobacz Przewodniki Szybki start.
- Aby dowiedzieć się więcej o strukturze zdarzeń niezwiązanych z telemetrią generowanych przez usługę IoT Hub, zobacz Schematy zdarzeń innych niż telemetria usługi IoT Hub.