Esaminare il set comune di funzionalità dei messaggi
Per supportare l'interoperabilità senza problemi tra i protocolli, l'hub IoT di Azure definisce un set comune delle funzionalità che sono disponibili in tutti i protocolli del dispositivo. Queste funzionalità di messaggistica possono essere usate sia nel routing dei messaggi da dispositivo a cloud che nei messaggi da cloud a dispositivo.
L'hub IoT di Azure implementa la messaggistica da dispositivo a cloud usando un modello di messaggistica di flusso. I messaggi da dispositivo a cloud dell'hub IoT di Azure sono più simili a eventi di Hub eventi che non a messaggi del bus di servizio, perché è presente un volume elevato di eventi che passano attraverso il servizio e sono leggibili da più lettori.
Un messaggio dell'hub IoT di Azure è costituito da:
- Un set predeterminato di proprietà di sistema, come descritto più avanti in questa unità.
- 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. L'hub IoT di Azure non modifica mai queste proprietà.
- Un corpo del messaggio, che può essere qualsiasi tipo di dati.
I nomi e i valori delle proprietà possono contenere solo caratteri alfanumerici ASCII e ! # $ % & ' * + - . ^ _ ``` | ~ quando si inviano messaggi da dispositivo a cloud usando il protocollo HTTPS o si inviano messaggi da cloud a dispositivo.
La messaggistica da dispositivo a cloud con l'hub IoT di Azure presenta le caratteristiche seguenti:
- I messaggi da dispositivo a cloud sono beni durevoli e conservati nell’endpoint messaggi/eventi predefinito di un hub IoT di Azure 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 di Azure non consente il partizionamento arbitrario. I messaggi da dispositivo a cloud vengono partizionati in base al valore deviceIddi origine.
- L'hub IoT di Azure consente l'autenticazione e il controllo di accesso a livello di singoli dispositivi.
- È possibile contrassegnare i messaggi con le informazioni contenute nelle proprietà dell'applicazione.
Per altre informazioni sulla codifica e la decodifica dei messaggi inviati tramite protocolli diversi, vedere Azure IoT SDK.
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 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.
Un corpo del messaggio instradabile valido può essere simile alla definizione seguente:
{
"timestamp": "2022-02-08T20:10:46Z",
"tag_name": "spindle_speed",
"tag_value": 100
}
Proprietà di sistema dei messaggi dell'hub IoT di Azure 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/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit. È possibile usare anche i caratteri seguenti - : . + % \ # * ? ! ( ) , = @ ; $ '.
Sì
messageId
iothub-enqueuedtime
Data e ora in cui il messaggio da dispositivo a cloud è stato ricevuto dall'hub IoT di Azure.
No
enqueuedTime
user-id
ID usato per specificare l'origine dei messaggi. Quando i messaggi vengono generati dall'hub IoT di Azure, quest’ultimo viene impostato su {Azure IoT Hub name}.
Sì
userId
iothub-connection-device-id
ID impostato dall'hub IoT di Azure nei 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 di Azure nei 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 di Azure nei messaggi da dispositivo a cloud. Contiene il valore connectionDeviceGenerationId (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 di Azure nei 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 di Azure 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à di sistema dei messaggi dell'hub IoT di Azure 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/minuscole (lunghezza massima 128 caratteri) con caratteri alfanumerici ASCII a 7 bit. È possibile usare anche i caratteri seguenti - : . + % _ # * ? ! ( ) , = @ ; $ '.
Sì
sequence-number
Numero (univoco per ogni coda di dispositivo) assegnato dall'hub IoT di Azure 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 dall'hub IoT di Azure, viene impostato su {nome hub IoT di Azure}.
Sì
iothub-ack
Generatore di messaggi con commenti. Questa proprietà viene usata nei messaggi da cloud a dispositivo per richiedere all'hub IoT di Azure di generare messaggi di feedback in seguito all'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. Per informazioni dettagliate, vedere la tabella seguente.
| 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 del dispositivo di connessione | iothub-connection-device-id | connectionDeviceId | iothub-connection-device-id | iothub-connection-device-id |
| ID del modulo di connessione | iothub-connection-module-id | connectionModuleId | iothub-connection-module-id | iothub-connection-module-id |
| ID di generazione dell'autenticazione della 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 di Azure misura le dimensioni dei messaggi in modo indipendente dal protocollo, considerando 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 del dispositivo nei messaggi da dispositivo a cloud, l'hub IoT di Azure 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 il deviceId e generationId del dispositivo di origine in base alle proprietà di identità del dispositivo.
La proprietà iothub-connection-auth-method contiene un oggetto serializzato JSON con le proprietà seguenti:
{
"scope": "{ hub | device }",
"type": "{ symkey | sas | x509 }",
"issuer": "iothub"
}