Tworzenie i odczytywanie komunikatów usługi IoT Hub
Aby zapewnić 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ń. Te funkcje mogą być używane zarówno w komunikatach 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 Hubs niż komunikaty usługi Service Bus w tym, że istnieje duża liczba zdarzeń przechodzących przez usługę, którą można odczytać 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 zgodnie z opisem w dalszej części tego artykułu.
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ć więcej informacji, zobacz przewodnik po protokole MQTT i przewodnik po protokole AMQP dla deweloperów, aby uzyskać szczegółowe informacje.
Podczas wysyłania komunikatów urządzenie-chmura przy użyciu protokołu HTTPS lub wysyłania komunikatów z chmury do urządzenia nazwy właściwości i wartości mogą zawierać tylko znaki alfanumeryczne ASCII oraz ! # $ % & ' * + - . ^ _ ` | ~ .
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.
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 analizowany zamiast zakodowanych danych binarnych base64), podaj odpowiedni typ zawartości i zestaw znaków dla komunikatu.
Aby użyć treści komunikatu w zapytaniu routingu usługi IoT Hub, podaj prawidłowy obiekt JSON komunikatu i ustaw właściwość typu zawartości komunikatu na application/json;charset=utf-8.
W poniższym przykładzie przedstawiono prawidłową treść komunikatu z routingiem:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Właściwości systemowe komunikatów z urządzenia do chmury
| 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 z uwzględnieniem wielkości liter (do 128 znaków) znaków alfanumerycznych ASCII 7-bitowych plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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. | 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 z urządzenia do chmury
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:16Z ale 2021-04-21T11:30:16-07:00 jest nieprawidłowy.
{
"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":{}
}
Właściwości systemu komunikatów z chmury do urządzenia
| 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 z uwzględnieniem wielkości liter (do 128 znaków) znaków alfanumerycznych ASCII 7-bitowych plus - : . + % _ # * ? ! ( ) , = @ ; $ '. |
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, identyfikator użytkownika to nazwa centrum IoT. | 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.
| Nazwa właściwości systemu | Event Hubs | Azure Storage | Service Bus | Event Grid |
|---|---|---|---|---|
| Identyfikator komunikatu | message-id | messageId | Identyfikator komunikatu | message-id |
| Identyfikator użytkownika | identyfikator użytkownika | Identyfikator użytkownika | Identyfikator użytkownika | identyfikator użytkownika |
| Identyfikator urządzenia połączenia | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| Identyfikator modułu połączenia | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| Identyfikator generowania uwierzytelniania połączenia | iothub-connection-auth-generation-id | connectionDeviceGenerationId | iothub-connection-auth-generation-id | iothub-connection-auth-generation-id |
| Metoda uwierzytelniania połączenia | iothub-connection-auth-method | connectionAuthMethod | iothub-connection-auth-method | iothub-connection-auth-method |
| contentType | typ zawartości | contentType | Typ zawartości | 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.