Creare e leggere messaggi dell'hub IoT
Per supportare l'interoperabilità tra protocolli, 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.
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 Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT 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 di hub IoT sono più simili Eventi di Hub eventi che bus di servizio messaggi in cui è presente un volume elevato 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.
Un 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 la Guida al protocollo MQTT e le guide per gli sviluppatori del protocollo AMQP per informazioni dettagliate.
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 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.
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 Arricchimenti dei messaggi.
Nota
Ogni protocollo dell'hub IoT fornisce una proprietà del tipo di contenuto del messaggio rispettata durante il routing dei dati agli endpoint personalizzati. Per fare in modo che i dati vengano gestiti correttamente nella destinazione (ad esempio, JSON viene considerato come una stringa analizzabile anziché come dati binari con codifica Base64), specificare 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, specificare 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 |
|---|---|---|---|
| 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 (fino a 128 caratteri) di caratteri alfanumerici ASCII a 7 bit più - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Sì | 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. | Sì | 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 quando si inviano i dati in 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 | 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. | 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 proprietà iothub-creation-time-utc 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, 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? |
|---|---|---|
| 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 (fino a 128 caratteri) di caratteri alfanumerici ASCII a 7 bit più - : . + % _ # * ? ! ( ) , = @ ; $ '. |
Sì |
| 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. | Sì |
| correlation-id | Proprietà stringa in un messaggio di risposta che contiene in genere il valore MessageId della richiesta nei modelli richiesta-risposta. | Sì |
| user-id | ID usato per specificare l'origine dei messaggi. Quando i messaggi vengono generati da hub IoT, 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 | 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 dall'hub IoT, vedere Schemi di eventi non di telemetria dell'hub IoT.