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.

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.

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à 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, mentre 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

Nomi delle proprietà di sistema

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

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.