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 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.