Udostępnij za pośrednictwem

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 komunikacja z chmury do urządzenia, bliźniaki urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie standardowej 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 i rozmiaru 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ądzenia do chmury w usłudze IoT Hub są bardziej podobne do zdarzeń w usłudze Event Hubs niż do komunikatów w usłudze Service Bus, ponieważ przez usługę przechodzi duża liczba zdarzeń, którą może odczytać wielu odbiorcó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 Komunikacja z centrum IoT przy użyciu protokołu MQTT i Komunikacja z centrum IoT przy użyciu protokołu AMQP.

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ą zawierać 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 przy użyciu identyfikatora Entra firmy Microsoft, usługa IoT Hub umożliwia uwierzytelnianie poszczególnych urządzeń i kontrolę dostępu.

  • Można oznaczyć komunikaty informacjami dodawanymi do właściwości aplikacji. Aby uzyskać więcej informacji, zobacz Wzbogacanie komunikatów IoT Hub z urządzeń do chmury.

Uwaga

Każdy protokół usługi IoT Hub udostępnia właściwość typu zawartości komunikatu, która jest uwzględniana podczas kierowania 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.

Poniższy przykład pokazuje prawidłową, trasowalną treść wiadomości.

{
    "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

Nieruchomość opis Możliwość ustawienia przez użytkownika? Słowo kluczowe dla
zapytania o trasowanie
identyfikator wiadomości Identyfikator ustawiany przez użytkownika dla wiadomości używanej w wzorcach żądanie-odpowiedź. Format: Ciąg znaków alfanumerycznych wrażliwy na wielkość liter, do 128 znaków, w kodowaniu 7-bitowym ASCII plus - : . + % _ # * ? ! ( ) , = @ ; $ '. Tak identyfikator wiadomości
iothub-enqueuedtime Data i godzina, kiedy usługa IoT Hub otrzymuje komunikat urządzenie-do-chmury. Nie. enqueuedTime
identyfikator użytkownika Identyfikator używany do określania źródła komunikatów. Tak Identyfikator użytkownika
identyfikator-urządzenia-połączenia-iothub Identyfikator ustawiony przez usługę IoT Hub w komunikatach z urządzenia do chmury. Zawiera identyfikator deviceId urządzenia, które wysłało komunikat. Nie. IdentyfikatorUrządzeniaPołączenia
iothub-connection-module-id (identyfikator modułu połączenia iothub) Identyfikator ustawiony przez usługę IoT Hub w komunikatach z urządzenia do chmury. Zawiera on identyfikator moduleId urządzenia, które wysłało komunikat. Nie. identyfikatorModułuPołączenia
Identyfikator generacji uwierzytelniania połączenia iothub Identyfikator ustawiony przez usługę IoT Hub w komunikatach z urządzenia do chmury. Zawiera on parametr connectionDeviceGenerationId (zgodnie z właściwościami tożsamości urządzenia) urządzenia, które wysłało komunikat. Nie. identyfikatorGeneracjiUrządzeniaPołączeniowego
metoda uwierzytelniania połączenia iothub 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. metodaUwierzytelnianiaPołączenia
iothub-app-iothub-czas-utworzenia-utc Umożliwia urządzeniu wysyłanie czasu tworzenia zdarzeń podczas wysyłania danych w partiach. Tak czas-utworzenia-utc
iothub-czas-utworzenia-utc Umożliwia urządzeniu wysyłanie czasu tworzenia zdarzeń podczas wysyłania jednej wiadomości naraz. Tak czas-utworzenia-utc
dt-schemat danych Centrum IoT ustawia tę wartość na wiadomościach od urządzenia do chmury. 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 $dt-temat

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 do zarejestrowania, gdy urządzenie wysyła komunikat. 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

Nieruchomość opis Możliwość ustawienia przez użytkownika?
identyfikator wiadomości Identyfikator ustawiany przez użytkownika dla wiadomości używanej w wzorcach żądanie-odpowiedź. Format: Ciąg znaków alfanumerycznych wrażliwy na wielkość liter, do 128 znaków, w kodowaniu 7-bitowym ASCII plus - : . + % _ # * ? ! ( ) , = @ ; $ '. Tak
numer sekwencji Liczba (unikatowa dla kolejki urządzeń) przypisana przez usługę IoT Hub do każdego komunikatu z chmury do urządzenia. Nie.
do Miejsce docelowe określone w komunikatach chmura-urządzenie . Nie.
termin upływu bezwzględnego Data i godzina wygaśnięcia wiadomości. Tak
identyfikator korelacji Właściwość typu string w komunikacie odpowiedzi, która zazwyczaj zawiera identyfikator MessageId żądania we wzorcach żądanie-odpowiedź. Tak
identyfikator użytkownika Identyfikator używany do określania źródła komunikatów. Gdy usługa IoT Hub generuje komunikaty, 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, aby poprosić IoT Hub o wygenerowanie informacji zwrotnych 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 Centra zdarzeń Azure Storage Magistrala usług Event Grid
Identyfikator komunikatu identyfikator wiadomości identyfikator wiadomości Identyfikator komunikatu identyfikator wiadomości
Identyfikator użytkownika identyfikator użytkownika Identyfikator użytkownika Identyfikator użytkownika identyfikator użytkownika
Identyfikator urządzenia połączenia identyfikator-urządzenia-połączenia-iothub IdentyfikatorUrządzeniaPołączenia identyfikator-urządzenia-połączenia-iothub identyfikator-urządzenia-połączenia-iothub
Identyfikator modułu połączenia iothub-connection-module-id (identyfikator modułu połączenia iothub) identyfikatorModułuPołączenia iothub-connection-module-id (identyfikator modułu połączenia iothub) iothub-connection-module-id (identyfikator modułu połączenia iothub)
Identyfikator generacji uwierzytelniania połączenia Identyfikator generacji uwierzytelniania połączenia iothub identyfikatorGeneracjiUrządzeniaPołączeniowego Identyfikator generacji uwierzytelniania połączenia iothub Identyfikator generacji uwierzytelniania połączenia iothub
Metoda uwierzytelniania połączenia metoda uwierzytelniania połączenia iothub metodaUwierzytelnianiaPołączenia metoda uwierzytelniania połączenia iothub metoda uwierzytelniania połączenia iothub
typ treści typ zawartości typ treści Typ zawartości iothub-content-type
Kodowanie zawartości kodowanie zawartości Kodowanie zawartości Kodowanie Treści kodowanie zawartości iothub
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime Nie dotyczy iothub-enqueuedtime
Identyfikator korelacji identyfikator korelacji correlationId (identyfikator korelacji) Identyfikator korelacji identyfikator korelacji
dt-schemat danych dt-schemat danych dt-schemat danych dt-schemat danych dt-schemat danych
dt-subject dt-subject Temat dt dt-temat 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 antyfałszujące

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
  • metoda uwierzytelniania połączenia iothub

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