Condividi tramite

Creare e leggere messaggi dell'hub IoT

Per supportare l'interoperabilità tra protocolli, l'hub IoT definisce un set comune di funzionalità di messaggistica disponibili in tutti i protocolli rivolti ai dispositivi. Queste funzionalità possono essere usate sia nei messaggi da dispositivo a cloud che nei messaggi da cloud a dispositivo.

Note

Alcune delle funzionalità indicate in questo articolo, come la messaggistica da cloud a dispositivo, i dispositivi gemelli e la gestione dei dispositivi, sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello e le dimensioni dell'hub IoT corretti per la soluzione.

L'hub IoT implementa la messaggistica da dispositivo a cloud usando un modello di messaggistica di flusso. I messaggi da dispositivo a cloud dell'IoT Hub sono più simili agli eventi di Event Hub rispetto ai messaggi del Service Bus, in quanto c'è un elevato volume di eventi che passano attraverso il servizio che più lettori possono leggere.

Un messaggio dell'hub IoT è costituito da:

  • Set predeterminato di proprietà di sistema, come descritto più avanti in questo articolo.

  • Un set di proprietà dell'applicazione. Dizionario di proprietà stringa che l'applicazione può definire e a cui può accedere senza dover deserializzare il corpo del messaggio. Queste proprietà non vengono mai modificate dall'hub IoT.

  • Corpo del messaggio, che può essere qualsiasi tipo di dati.

Ogni protocollo del dispositivo implementa le proprietà di impostazione in modi diversi. Per altre informazioni, vedere Comunicare con un hub IoT usando il protocollo MQTT e Comunicare con l'hub IoT usando il protocollo AMQP.

Quando si inviano messaggi da dispositivo a cloud usando il protocollo HTTPS o si inviano messaggi da cloud a dispositivo, i nomi e i valori delle proprietà possono contenere solo caratteri alfanumerici ASCII, più ! # $ % & ' * + - . ^ _ ` | ~ .

La messaggistica da dispositivo a cloud con hub IoT ha le caratteristiche seguenti:

  • I messaggi da dispositivo a cloud sono durevoli e vengono mantenuti nell'endpoint messages/events predefinito in un hub IoT per un massimo di sette giorni.

  • I messaggi da dispositivo a cloud possono essere al massimo di 256 KB e possono essere raggruppati in batch per ottimizzare gli invii. I batch possono avere dimensioni massime pari a 256 KB.

  • L'hub IoT non consente il partizionamento arbitrario. I messaggi da dispositivo a cloud vengono partizionati in base al valore deviceIddi origine.

  • Come illustrato in Controllare l'accesso all'hub IoT usando Microsoft Entra ID, l'hub IoT abilita l'autenticazione e il controllo di accesso per dispositivo.

  • È possibile contrassegnare i messaggi con le informazioni contenute nelle proprietà dell'applicazione. Per altre informazioni, vedere Arricchimenti di messaggi per l'IoT Hub da dispositivo a cloud.

Note

Ogni protocollo dell'hub IoT fornisce una proprietà del tipo di contenuto del messaggio, che viene rispettata durante il routing dei dati agli endpoint personalizzati. Per gestire correttamente i dati nella destinazione, ad esempio JSON considerato come stringa analizzabile anziché dati binari con codifica Base64, fornire il tipo di contenuto e il set di caratteri appropriati per il messaggio.

Per usare il corpo del messaggio in una query di routing dell'hub IoT, fornire un oggetto JSON valido per il messaggio e impostare la proprietà del tipo di contenuto del messaggio su application/json;charset=utf-8.

L'esempio seguente mostra un corpo del messaggio instradabile valido:

{
    "timestamp": "2022-02-08T20:10:46Z",
    "tag_name": "spindle_speed",
    "tag_value": 100
}

Proprietà di sistema dei messaggi da dispositivo a cloud

Proprietà Descrizione Definibile dall'utente? Parola chiave per
query di routing
ID messaggio Un identificatore configurabile dall'utente per il messaggio, usato per i modelli di richiesta-risposta. Formato: stringa con distinzione tra maiuscole e minuscole (fino a 128 caratteri) di caratteri alfanumerici ASCII a 7 bit più - : . + % _ # * ? ! ( ) , = @ ; $ '. Sì ID messaggio
iothub-enqueuedtime Data e ora in cui l'hub IoT riceve il messaggio da dispositivo a cloud . NO enqueuedTime
ID utente ID usato per specificare l'origine dei messaggi. Sì ID utente
iothub-connection-device-id ID impostato dall'hub IoT sui messaggi da dispositivo a cloud. Contiene il valore deviceId del dispositivo che ha inviato il messaggio. NO ID del dispositivo di connessione
iothub-connection-module-id ID impostato dall'hub IoT sui messaggi da dispositivo a cloud. Contiene il valore moduleId del dispositivo che ha inviato il messaggio. NO connectionModuleId
iothub-connection-auth-generation-id ID impostato dall'hub IoT sui messaggi da dispositivo a cloud. Contiene il valore connectionDeviceGenerationId (come indicato in Proprietà delle identità dei dispositivi) del dispositivo che ha inviato il messaggio. NO connectionDeviceGenerationId
iothub-connection-auth-method Metodo di autenticazione impostato dall'hub IoT sui messaggi da dispositivo a cloud. Questa proprietà contiene informazioni sul metodo di autenticazione usato per autenticare il dispositivo che invia il messaggio. NO Metodo di autenticazione della connessione
iothub-app-iothub-creation-time-utc Consente al dispositivo di inviare l'ora di creazione dell'evento durante l'invio di dati in un batch. Sì creation-time-utc
iothub-creation-time-utc Consente al dispositivo di inviare l'ora di creazione dell'evento quando si invia un messaggio alla volta. Sì creation-time-utc
dt-dataschema L'hub IoT imposta questo valore nei messaggi da dispositivo a cloud. Contiene l'ID del modello di dispositivo impostato nella connessione del dispositivo. NO $dt-dataschema
dt-subject Nome del componente che invia i messaggi da dispositivo a cloud. Sì $dt-subject

Proprietà dell'applicazione dei messaggi da dispositivo a cloud

Un uso comune delle proprietà dell'applicazione consiste nell'inviare un timestamp dal dispositivo usando la iothub-creation-time-utc proprietà per registrare quando il dispositivo invia il messaggio. Il formato di questo timestamp deve essere UTC senza informazioni sul fuso orario. Ad esempio, 2021-04-21T11:30:16Z è valido, ma 2021-04-21T11:30:16-07:00 non è valido.

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

Proprietà di sistema dei messaggi da cloud a dispositivo

Proprietà Descrizione Definibile dall'utente?
ID messaggio Un identificatore configurabile dall'utente per il messaggio, usato per i modelli di richiesta-risposta. Formato: stringa con distinzione tra maiuscole e minuscole (fino a 128 caratteri) di caratteri alfanumerici ASCII a 7 bit più - : . + % _ # * ? ! ( ) , = @ ; $ '. Sì
numero di sequenza Numero, univoco per ogni dispositivo-coda, assegnato dall'hub IoT a ogni messaggio da cloud a dispositivo. NO
to Destinazione specificata nei messaggi da cloud a dispositivo . NO
tempo di scadenza assoluto Data e ora della scadenza del messaggio. Sì
ID di correlazione Proprietà stringa in un messaggio di risposta che contiene in genere il valore MessageId della richiesta nei modelli richiesta-risposta. Sì
ID utente ID usato per specificare l'origine dei messaggi. Quando l'hub IoT genera messaggi, l'ID utente è il nome dell'hub IoT. Sì
iothub-ack Generatore di messaggi con commenti. Questa proprietà viene usata nei messaggi da cloud a dispositivo per richiedere all'hub IoT di generare messaggi con commenti come risultato dell'utilizzo del messaggio da parte del dispositivo. I valori possibili sono i seguenti: none (predefinito): non viene generato alcun messaggio con commenti, positive: si riceve un messaggio con commenti se il messaggio è stato completato, negative: si riceve un messaggio con commenti se il messaggio è scaduto o se è stato raggiunto il numero massimo di recapiti senza il completamento da parte del dispositivo, full: sia per esito positivo che negativo. Sì

Nomi delle proprietà di sistema

I nomi delle proprietà di sistema variano in base all'endpoint a cui vengono indirizzati i messaggi.

Nome della proprietà di sistema Hub eventi Archiviazione di Azure Bus di servizio Griglia di eventi
ID del messaggio ID messaggio ID messaggio MessageId ID messaggio
ID utente ID utente ID utente UserId ID utente
ID dispositivo di connessione iothub-connection-device-id ID del dispositivo di connessione iothub-connection-device-id iothub-connection-device-id
ID modulo di connessione iothub-connection-module-id connectionModuleId iothub-connection-module-id iothub-connection-module-id
ID generazione autenticazione connessione iothub-connection-auth-generation-id connectionDeviceGenerationId iothub-connection-auth-generation-id iothub-connection-auth-generation-id
Metodo di autenticazione della connessione iothub-connection-auth-method Metodo di autenticazione della connessione iothub-connection-auth-method iothub-connection-auth-method
tipo di contenuto tipo di contenuto tipo di contenuto TipoDiContenuto iothub-content-type
contentEncoding codifica del contenuto contentEncoding ContentEncoding iothub-content-encoding
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime N/D iothub-enqueuedtime
IdentificatoreDiCorrelazione ID di correlazione correlationId IdentificatoreDiCorrelazione ID di correlazione
dt-dataschema dt-dataschema dt-dataschema dt-dataschema dt-dataschema
dt-subject dt-subject dt-subject dt-subject dt-subject

Dimensioni dei messaggi

L'hub IoT misura le dimensioni dei messaggi in modo indipendente dal protocollo, prendendo in considerazione solo il payload effettivo. Le dimensioni in byte vengono calcolate come somma dei valori seguenti:

  • Dimensioni del corpo in byte.
  • Dimensioni in byte di tutti i valori delle proprietà di sistema dei messaggi.
  • Dimensioni in byte di tutti i nomi e i valori delle proprietà dell'utente.

I nomi e i valori delle proprietà sono limitati ai caratteri ASCII, in modo che la lunghezza delle stringhe sia uguale alle dimensioni in byte.

Proprietà anti-spoofing

Per evitare lo spoofing di dispositivi nei messaggi da dispositivo a cloud, l'hub IoT contrassegna tutti i messaggi con le proprietà seguenti:

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

Le prime due contengono le proprietà deviceId e generationId del dispositivo di origine, come indicato in Proprietà delle identità dei dispositivi.

La proprietà iothub-connection-auth-method contiene un oggetto serializzato JSON con le proprietà seguenti:

{
  "scope": "{ hub | device | module }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

Passaggi successivi

  • Last updated on