Creare e leggere messaggi dell'hub IoT

Per supportare l'interoperabilità senza problemi tra protocolli, hub IoT definisce un set comune di funzionalità di messaggistica disponibili in tutti i protocolli rivolti ai dispositivi. Possono essere usati sia nel routing dei messaggi da dispositivo a cloud che nei messaggi da cloud a dispositivo.

Nota

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 basic e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato 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'hub IoT sono più simili a eventi di Hub eventi che non a messaggi del bus di servizio, poiché è presente un volume elevato di eventi che passano attraverso il servizio e sono leggibili tramite più lettori.

Un messaggio dell'hub IoT è costituito da:

  • Un set di predeterminato di proprietà di sistema come indicato di seguito.

  • 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 informazioni dettagliate, vedere le guide per sviluppatori MQTT e AMQP correlate.

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

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 avere dimensioni massime pari a 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, l'hub IoT consente il controllo di accesso e l'autenticazione per singoli dispositivi.

  • È possibile contrassegnare i messaggi con le informazioni contenute nelle proprietà dell'applicazione. Per altre informazioni, vedere la pagina relativa agli arricchimenti dei messaggi.

Per altre informazioni sulla codifica e la decodifica dei messaggi inviati tramite protocolli diversi, vedere Azure IoT SDK.

Nota

Ogni protocollo hub IoT fornisce una proprietà del tipo di contenuto del messaggio 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), è necessario 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 hub IoT, è necessario fornire un oggetto JSON valido per il messaggio e impostare la proprietà del tipo di contenuto del messaggio su application/json;charset=utf-8.

Un corpo del messaggio instradabile valido può essere simile al seguente:

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

Proprietà di sistema dei messaggi dell'hub IoT da dispositivo a cloud

Proprietà Descrizione Definibile dall'utente? Parola chiave per
la query di routing
message-id Un identificatore configurabile dall'utente per il messaggio, usato per i modelli di richiesta-risposta. Formato: stringa con distinzione tra maiuscole e minuscole (con lunghezza massima di 128 caratteri) di caratteri alfanumerici ASCII a 7 bit + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. messageId
iothub-enqueuedtime Data e ora di ricezione del messaggio da dispositivo a cloud da parte dell'hub IoT. No enqueuedTime
user-id ID usato per specificare l'origine dei messaggi. Quando i messaggi vengono generati dall'hub IoT, viene impostata su {iot hub name}. userId
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 connectionDeviceId
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 connectionAuthMethod
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. 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. creation-time-utc
dt-dataschema Questo valore viene impostato dall'hub IoT nei messaggi da dispositivo a cloud. Contiene l'ID modello di dispositivo impostato nella connessione del dispositivo. No $dt-dataschema
dt-subject Nome del componente che invia i messaggi da dispositivo a cloud. $dt-subject

Proprietà dell'applicazione dei messaggi di hub IoT D2C

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 messaggio è stato inviato dal dispositivo. Il formato di questo timestamp deve essere UTC senza informazioni sul fuso orario. Ad esempio, 2021-04-21T11:30:16Z è valido, 2021-04-21T11:30:16-07:00 non è valido:

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

Proprietà di sistema dei messaggi dell'hub IoT da cloud a dispositivo

Proprietà Descrizione Definibile dall'utente?
message-id Un identificatore configurabile dall'utente per il messaggio, usato per i modelli di richiesta-risposta. Formato: stringa con distinzione tra maiuscole e minuscole (con lunghezza massima di 128 caratteri) di caratteri alfanumerici ASCII a 7 bit + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}.
sequence-number 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
absolute-expiry-time Data e ora della scadenza del messaggio.
correlation-id Proprietà stringa in un messaggio di risposta che contiene in genere il valore MessageId della richiesta nei modelli richiesta-risposta.
user-id ID usato per specificare l'origine dei messaggi. Quando i messaggi vengono generati dall'hub IoT, viene impostata su {iot hub name}.
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.

Nomi delle proprietà di sistema

I nomi delle proprietà di sistema variano in base all'endpoint a cui vengono indirizzati i messaggi. Per informazioni dettagliate su questi nomi, vedere la tabella seguente.

Nome della proprietà di sistema Hub eventi di Archiviazione di Azure Bus di servizio Griglia di eventi
ID del messaggio message-id messageId MessageId message-id
ID utente user-id userId ID utente user-id
ID dispositivo di connessione iothub-connection-device-id connectionDeviceId 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 connectionAuthMethod iothub-connection-auth-method iothub-connection-auth-method
contentType content-type contentType ContentType iothub-content-type
contentEncoding content-encoding contentEncoding ContentEncoding iothub-content-encoding
iothub-enqueuedtime iothub-enqueuedtime enqueuedTime N/D iothub-enqueuedtime
CorrelationId correlation-id correlationId CorrelationId correlation-id
dt-dataschema dt-dataschema dt-dataschema dt-dataschema dt-dataschema
dt-subject dt-subject dt-subject dt-subject dt-subject

Dimensione del messaggio

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

  • Per informazioni sulla dimensione massima dei messaggi nell'hub IoT, vedere Quote e limitazioni dell'hub IoT.
  • Per informazioni su come creare e leggere i messaggi dell'hub IoT in diversi linguaggi di programmazione, vedere le guide introduttive.
  • Per informazioni sulla struttura degli eventi non di telemetria generati da hub IoT, vedere hub IoT schemi di eventi non di telemetria.