Comunicare con l'hub IoT tramite il protocollo MQTTCommunicate with your IoT hub using the MQTT protocol

L'hub IoT consente ai dispositivi di comunicare con gli endpoint dei dispositivi dell'hub IoT usando:IoT Hub enables devices to communicate with the IoT Hub device endpoints using:

  • MQTT v3.1.1 sulla porta 8883MQTT v3.1.1 on port 8883
  • MQTT v3.1.1 sul WebSocket sulla porta 443.MQTT v3.1.1 over WebSocket on port 443.

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.Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT hub. Per altre informazioni sui livelli Basic e Standard dell'hub IoT, vedere come scegliere il livello corretto dell'hub IoT.For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

Tutte le comunicazioni del dispositivo con l'hub IoT devono essere protette tramite TLS/SSL.All device communication with IoT Hub must be secured using TLS/SSL. Pertanto, l'hub IoT non supporta le connessioni non protette sulla porta 1883.Therefore, IoT Hub doesn’t support non-secure connections over port 1883.

Connessione all'hub IoTConnecting to IoT Hub

Un dispositivo può usare il protocollo MQTT per connettersi a un hub IoT usando:A device can use the MQTT protocol to connect to an IoT hub using:

  • Librerie negli Azure IoT SDK oppureEither the libraries in the Azure IoT SDKs.
  • Direttamente il protocollo MQTT.Or the MQTT protocol directly.

Uso degli SDK per dispositiviUsing the device SDKs

Gli SDK per dispositivi che supportano il protocollo MQTT sono disponibili per Java, Node.js, C, C# e Python.Device SDKs that support the MQTT protocol are available for Java, Node.js, C, C#, and Python. Gli SDK per dispositivi usano la stringa di connessione dell'hub IoT standard per stabilire una connessione a un hub IoT.The device SDKs use the standard IoT Hub connection string to establish a connection to an IoT hub. Per usare il protocollo MQTT, il parametro del protocollo del client deve essere impostato su MQTT.To use the MQTT protocol, the client protocol parameter must be set to MQTT. Per impostazione predefinita, gli SDK per dispositivi si connettono a un hub IoT con il flag CleanSession impostato su 0 e usano QoS 1 per lo scambio di messaggi con l'hub IoT.By default, the device SDKs connect to an IoT Hub with the CleanSession flag set to 0 and use QoS 1 for message exchange with the IoT hub.

Quando un dispositivo è connesso a un hub IoT, gli SDK per dispositivi forniscono i metodi che consentono al dispositivo di scambiare messaggi con un hub IoT.When a device is connected to an IoT hub, the device SDKs provide methods that enable the device to exchange messages with an IoT hub.

La tabella seguente include i collegamenti a esempi di codice per ogni linguaggio supportato e specifica il parametro da usare per stabilire una connessione all'hub IoT con il protocollo MQTT.The following table contains links to code samples for each supported language and specifies the parameter to use to establish a connection to IoT Hub using the MQTT protocol.

LinguaggioLanguage Parametro del protocolloProtocol parameter
Node.jsNode.js azure-iot-device-mqttazure-iot-device-mqtt
JavaJava IotHubClientProtocol.MQTTIotHubClientProtocol.MQTT
CC MQTT_ProtocolMQTT_Protocol
C#C# TransportType.MqttTransportType.Mqtt
PythonPython IoTHubTransportProvider.MQTTIoTHubTransportProvider.MQTT

Migrazione di un'app per dispositivo da AMQP a MQTTMigrating a device app from AMQP to MQTT

Se si usano gli SDK per dispositivi, per passare da AMQP a MQTT è necessario modificare il parametro del protocollo nell'inizializzazione client come indicato in precedenza.If you are using the device SDKs, switching from using AMQP to MQTT requires changing the protocol parameter in the client initialization as stated previously.

Quando si esegue questa operazione, controllare gli elementi seguenti:When doing so, make sure to check the following items:

  • AMQP restituisce errori per diverse condizioni, mentre MQTT termina la connessione.AMQP returns errors for many conditions, while MQTT terminates the connection. Di conseguenza, la logica di gestione delle eccezioni potrebbe richiedere alcune modifiche.As a result your exception handling logic might require some changes.
  • MQTT non supporta le operazioni di rifiuto quando si ricevono messaggi da cloud a dispositivo.MQTT does not support the reject operations when receiving cloud-to-device messages. Se l'app back-end deve ricevere una risposta dall'app per dispositivo, considerare la possibilità di usare metodi diretti.If your back-end app needs to receive a response from the device app, consider using direct methods.

Uso del protocollo MQTT direttamenteUsing the MQTT protocol directly

Se un dispositivo non può usare gli SDK per dispositivi, può comunque connettersi agli endpoint pubblici del dispositivo tramite il protocollo MQTT sulla porta 8883.If a device cannot use the device SDKs, it can still connect to the public device endpoints using the MQTT protocol on port 8883. Nel pacchetto CONNECT il dispositivo deve usare i valori seguenti:In the CONNECT packet the device should use the following values:

  • Per il campo ClientId usare deviceId.For the ClientId field, use the deviceId.

  • Per il campo Username usare {iothubhostname}/{device_id}/api-version=2016-11-14, dove {iothubhostname} rappresenta il record CName completo dell'hub IoT.For the Username field, use {iothubhostname}/{device_id}/api-version=2016-11-14, where {iothubhostname} is the full CName of the IoT hub.

    Ad esempio, se il nome dell'hub IoT è contoso.azure-devices.net e il nome del dispositivo è MyDevice01, il campo Username completo deve contenere:For example, if the name of your IoT hub is contoso.azure-devices.net and if the name of your device is MyDevice01, the full Username field should contain:

    contoso.azure-devices.net/MyDevice01/api-version=2016-11-14

  • Per il campo Password usare un token di firma di accesso condiviso.For the Password field, use a SAS token. Il formato del token di firma di accesso condiviso è identico a quello per i protocolli HTTPS e AMQP:The format of the SAS token is the same as for both the HTTPS and AMQP protocols:

    SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    Nota

    Le password di token SAS non sono obbligatorie se si usa l'autenticazione dei certificati X.509.If you use X.509 certificate authentication, SAS token passwords are not required. Per altre informazioni, vedere Configurare la sicurezza X.509 nell'hub IoT di AzureFor more information, see Set up X.509 security in your Azure IoT Hub

    Per altre informazioni su come generare i token di firma di accesso condiviso, vedere la sezione sui dispositivi nell'articolo Uso dei token di sicurezza dell'hub IoT.For more information about how to generate SAS tokens, see the device section of Using IoT Hub security tokens.

    Durante il test è anche possibile usare lo strumento Device Explorer per generare rapidamente un token di firma di accesso condiviso da copiare e incollare nel codice:When testing, you can also use the device explorer tool to quickly generate a SAS token that you can copy and paste into your own code:

    1. Andare alla scheda Management (Gestione) di Device Explorer.Go to the Management tab in Device Explorer.
    2. Fare clic su SAS Token in alto a destra.Click SAS Token (top right).
    3. In SASTokenForm selezionare il dispositivo nell'elenco a discesa DeviceID.On SASTokenForm, select your device in the DeviceID drop down. Impostare il valore TTL.Set your TTL.
    4. Fare clic su Generate per creare il token.Click Generate to create your token.

      Il token SAS generato ha questa struttura:The SAS token that's generated has the following structure:

      HostName={your hub name}.azure-devices.net;DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

      La porzione di questo token da usare come campo Password per connettersi usando MQTT è:The part of this token to use as the Password field to connect using MQTT is:

      SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Per i pacchetti di connessione e disconnessione di MQTT l'hub IoT genera un evento nel canale Monitoraggio operazioni .For MQTT connect and disconnect packets, IoT Hub issues an event on the Operations Monitoring channel. Questo evento contiene informazioni aggiuntive che consentono di risolvere i problemi di connettività.This event has additional information that can help you to troubleshoot connectivity issues.

L'app per dispositivo può specificare un messaggio Will nel pacchetto CONNECT.The device app can specify a Will message in the CONNECT packet. L'app per dispositivo deve usare devices/{device_id}/messages/events/{property_bag} o devices/{device_id}/messages/events/{property_bag} come nome di argomento Will per definire i messaggi Will da inoltrare come messaggi di telemetria.The device app should use devices/{device_id}/messages/events/{property_bag} or devices/{device_id}/messages/events/{property_bag} as the Will topic name to define Will messages to be forwarded as a telemetry message. In questo caso, se la connessione di rete viene chiusa, ma il dispositivo non ha prima ricevuto un pacchetto DISCONNECT, l'hub IoT invia il messaggio Will specificato nel pacchetto CONNECT al canale di telemetria.In this case, if the network connection is closed, but a DISCONNECT packet was not previously received from the device, then IoT Hub sends the Will message supplied in the CONNECT packet to the telemetry channel. Quest'ultimo può essere l'endpoint Events predefinito o un endpoint personalizzato definito dal routing dell'hub IoT.The telemetry channel can be either the default Events endpoint or a custom endpoint defined by IoT Hub routing. Alla proprietà iothub-MessageType del messaggio è assegnato un valore Will.The message has the iothub-MessageType property with a value of Will assigned to it.

Configurazione TLS/SSLTLS/SSL configuration

Per usare direttamente il protocollo MQTT, il client deve connettersi tramite TLS/SSL,To use the MQTT protocol directly, your client must connect over TLS/SSL. altrimenti si verificheranno errori di connessione.Attempts to skip this step fail with connection errors.

Per stabilire una connessione TLS, potrebbe essere necessario scaricare e fare riferimento al DigiCert Baltimore Root Certificate,In order to establish a TLS connection, you may need to download and reference the DigiCert Baltimore Root Certificate. Questo certificato è quello usato da Azure per proteggere la connessione.This certificate is the one that Azure uses to secure the connection. È possibile trovare il certificato nel repository Azure-iot-sdk-c.You can find this certificate in the Azure-iot-sdk-c repository. Altre informazioni su questi certificati sono disponibili nel sito Web di Digicert.More information about these certificates can be found on Digicert's website.

Di seguito un esempio di implementazione che usa la versione Python della libreria Paho MQTT di Eclipse Foundation.An example of how to implement this using the Python version of the Paho MQTT library by the Eclipse Foundation might look like the following.

È prima necessario installare la libreria Paho dall'ambiente della riga di comando:First, install the Paho library from your command-line environment:

pip install paho-mqtt

Implementare poi il client in uno script Python.Then, implement the client in a Python script. Sostituire i segnaposto come segue:Replace the placeholders as follows:

  • <local path to digicert.cer> è il percorso in un file locale che contiene il certificato radice DigiCert Baltimore.<local path to digicert.cer> is the path to a local file that contains the DigiCert Baltimore Root certificate. È possibile creare questo file copiando le informazioni sul certificato da certs.c negli Azure IoT SDK per C. Includere le righe -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----, rimuovere i contrassegni " all'inizio e alla fine di ogni riga e rimuovere i caratteri \r\n alla fine di ogni riga.You can create this file by copying the certificate information from certs.c in the Azure IoT SDK for C. Include the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, remove the " marks at the beginning and end of every line, and remove the \r\n characters at the end of every line.
  • <device id from device registry> è l'ID di un dispositivo che è stato aggiunto all'hub IoT.<device id from device registry> is the ID of a device you added to your IoT hub.
  • <generated SAS token> è un token SAS per il dispositivo creato come descritto in precedenza in questo articolo.<generated SAS token> is a SAS token for the device created as described previously in this article.
  • <iot hub name> nome dell'hub IoT.<iot hub name> the name of your IoT hub.
from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"

def on_connect(client, userdata, flags, rc):
  print ("Device connected with result code: " + str(rc))
def on_disconnect(client, userdata, rc):
  print ("Device disconnected with result code: " + str(rc))
def on_publish(client, userdata, mid):
  print ("Device sent message")

client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" + device_id, password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None, cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", "{id=123}", qos=1)
client.loop_forever()

Invio di messaggi da dispositivo a cloudSending device-to-cloud messages

Dopo avere stabilito una connessione, un dispositivo può inviare messaggi all'hub IoT usando devices/{device_id}/messages/events/ o devices/{device_id}/messages/events/{property_bag} come nome di argomento.After making a successful connection, a device can send messages to IoT Hub using devices/{device_id}/messages/events/ or devices/{device_id}/messages/events/{property_bag} as a Topic Name. L'elemento {property_bag} consente al dispositivo di inviare messaggi con proprietà aggiuntive in un formato con codifica URL.The {property_bag} element enables the device to send messages with additional properties in a url-encoded format. Ad esempio: For example:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Nota

Questo elemento {property_bag} usa la stessa codifica delle stringhe di query nel protocollo HTTPS.This {property_bag} element uses the same encoding as for query strings in the HTTPS protocol.

Di seguito è riportato un elenco di comportamenti specifici dell'implementazione dell'hub IoT:The following is a list of IoT Hub implementation-specific behaviors:

  • L'hub IoT non supporta i messaggi di QoS 2.IoT Hub does not support QoS 2 messages. Quando un'app per dispositivo pubblica un messaggio con QoS 2, l'hub IoT chiude la connessione di rete.If a device app publishes a message with QoS 2, IoT Hub closes the network connection.
  • L'hub IoT non rende persistenti i messaggi di mantenimento.IoT Hub does not persist Retain messages. Se un dispositivo invia un messaggio con il flag RETAIN impostato su 1, l'hub IoT aggiunge al messaggio la proprietà dell'applicazione x-opt-retain.If a device sends a message with the RETAIN flag set to 1, IoT Hub adds the x-opt-retain application property to the message. In tal caso, anziché rendere persistente il messaggio di mantenimento, l'hub IoT passa invece all'app back-end.In this case, instead of persisting the retain message, IoT Hub passes it to the backend app.
  • L'hub IoT supporta solo una connessione MQTT attiva per ogni dispositivo.IoT Hub only supports one active MQTT connection per device. Qualsiasi nuova connessione MQTT per conto dello stesso ID di dispositivo causa la perdita della connessione esistente da parte dell'hub IoT.Any new MQTT connection on behalf of the same device ID causes IoT Hub to drop the existing connection.

Per altre informazioni, vedere Guida per gli sviluppatori sulla messaggistica.For more information, see Messaging developer's guide.

Ricezione di messaggi da cloud a dispositivoReceiving cloud-to-device messages

Per ricevere messaggi dall'hub IoT, un dispositivo deve eseguire la sottoscrizione con devices/{device_id}/messages/devicebound/# come filtro di argomento.To receive messages from IoT Hub, a device should subscribe using devices/{device_id}/messages/devicebound/# as a Topic Filter. Il carattere jolly a più livelli # nel filtro argomento viene usato solo per consentire al dispositivo di ricevere proprietà aggiuntive nel nome dell'argomento.The multi-level wildcard # in the Topic Filter is used only to allow the device to receive additional properties in the topic name. L'hub IoT non consente l'uso dei caratteri jolly # o ? per il filtro di argomenti secondari.IoT Hub does not allow the usage of the # or ? wildcards for filtering of subtopics. Poiché l'hub IoT non è un broker di messaggistica di pubblicazione e sottoscrizione generico, supporta solo i nomi di argomento e i filtri di argomento documentati.Since IoT Hub is not a general-purpose pub-sub messaging broker, it only supports the documented topic names and topic filters.

Il dispositivo non riceverà i messaggi dall'hub IoT prima di aver effettuato la sottoscrizione all'endpoint del dispositivo specifico, rappresentato dal filtro argomento devices/{device_id}/messages/devicebound/#.The device does not receive any messages from IoT Hub, until it has successfully subscribed to its device-specific endpoint, represented by the devices/{device_id}/messages/devicebound/# topic filter. Dopo aver stabilito la sottoscrizione, il dispositivo inizierà a ricevere i messaggi da cloud a dispositivo che gli sono stati inviati dopo la sottoscrizione.After a subscription has been established, the device receives cloud-to-device messages that were sent to it after the time of the subscription. Se il dispositivo si connette con il flag CleanSession impostato su 0, la sottoscrizione sarà mantenuta tra sessioni diverse.If the device connects with CleanSession flag set to 0, the subscription is persisted across different sessions. In questo caso, alla connessione successiva con CleanSession 0 il dispositivo riceverà i messaggi in sospeso che gli sono stati inviati mentre era disconnesso.In this case, the next time the device connects with CleanSession 0 it receives any outstanding messages sent to it while disconnected. Se il dispositivo usa il flag CleanSession impostato su 1 tuttavia, non riceverà i messaggi dall'hub IoT fino a quando non si registra presso l'endpoint del dispositivo.If the device uses CleanSession flag set to 1 though, it does not receive any messages from IoT Hub until it subscribes to its device-endpoint.

L'hub IoT recapita i messaggi con il nome di argomento devices/{device_id}/messages/devicebound/ o devices/{device_id}/messages/devicebound/{property_bag} se sono presenti proprietà dei messaggi.IoT Hub delivers messages with the Topic Name devices/{device_id}/messages/devicebound/, or devices/{device_id}/messages/devicebound/{property_bag} when there are message properties. {property_bag} contiene coppie chiave/valore con codifica URL di proprietà dei messaggi.{property_bag} contains url-encoded key/value pairs of message properties. Solo le proprietà dell'applicazione e le proprietà di sistema configurabili dall'utente, ad esempio messageId o correlationId, sono incluse nel contenitore delle proprietà.Only application properties and user-settable system properties (such as messageId or correlationId) are included in the property bag. I nomi delle proprietà di sistema hanno il prefisso $. Le proprietà dell'applicazione usano il nome della proprietà originale senza il prefisso.System property names have the prefix $, application properties use the original property name with no prefix.

Quando un'app del dispositivo esegue una sottoscrizione a un argomento con QoS 2, l'hub IoT concede il livello QoS 1 massimo nel pacchetto SUBACK.When a device app subscribes to a topic with QoS 2, IoT Hub grants maximum QoS level 1 in the SUBACK packet. Successivamente, l'hub IoT invierà i messaggi al dispositivo tramite QoS 1.After that, IoT Hub delivers messages to the device using QoS 1.

Recupero delle proprietà dei dispositivi gemelliRetrieving a device twin's properties

Un dispositivo effettua la sottoscrizione a $iothub/twin/res/# per ricevere le risposte dell'operazione.First, a device subscribes to $iothub/twin/res/#, to receive the operation's responses. Invia quindi un messaggio vuoto all'argomento $iothub/twin/GET/?$rid={request id}, con un valore popolato per request ID.Then, it sends an empty message to topic $iothub/twin/GET/?$rid={request id}, with a populated value for request ID. Il servizio invierà quindi un messaggio di risposta con i dati del dispositivo gemello nell'argomento $iothub/twin/res/{status}/?$rid={request id}, usando lo stesso request ID della richiesta.The service then sends a response message containing the device twin data on topic $iothub/twin/res/{status}/?$rid={request id}, using the same request ID as the request.

Request ID può essere qualsiasi valore valido per il valore della proprietà di un messaggio, come descritto nella Guida per gli sviluppatori sulla messaggistica dell'hub IoT, e lo stato viene convalidato come valore intero.Request ID can be any valid value for a message property value, as per IoT Hub messaging developer's guide, and status is validated as an integer.

Il corpo della risposta contiene la sezione delle proprietà del dispositivo gemello.The response body contains the properties section of the device twin. Il frammento di codice seguente mostra il corpo della voce del registro delle identità limitato al membro "properties", ad esempio:The following snippet shows the body of the identity registry entry limited to the "properties" member, for example:

{
    "properties": {
        "desired": {
            "telemetrySendFrequency": "5m",
            "$version": 12
        },
        "reported": {
            "telemetrySendFrequency": "5m",
            "batteryLevel": 55,
            "$version": 123
        }
    }
}

I possibili codici di stato sono i seguenti:The possible status codes are:

StatusStatus DESCRIZIONEDescription
200200 SuccessSuccess
429429 Numero eccessivo di richieste (limitazione), come descritto in Limitazione dell'hub IoTToo many requests (throttled), as per IoT Hub throttling
55 Errori serverServer errors

Per altre informazioni, vedere la Guida per gli sviluppatori sui dispositivi gemelli.For more information, see Device twins developer's guide.

Aggiornare le proprietà segnalate di un dispositivo gemelloUpdate device twin's reported properties

La sequenza seguente descrive in che modo un dispositivo aggiorna le proprietà dichiarate in un dispositivo gemello nell'hub IoT:The following sequence describes how a device updates the reported properties in the device twin in IoT Hub:

  1. Un dispositivo deve prima sottoscrivere l'argomento $iothub/twin/res/# per ricevere le risposte dell'operazione dall'hub IoT.A device must first subscribe to the $iothub/twin/res/# topic to receive the operation's responses from IoT Hub.

  2. Un dispositivo invia un messaggio che contiene l'aggiornamento di un dispositivo gemello per l'argomento $iothub/twin/PATCH/properties/reported/?$rid={request id}.A device sends a message that contains the device twin update to the $iothub/twin/PATCH/properties/reported/?$rid={request id} topic. Questo messaggio include un valore request ID.This message includes a request ID value.

  3. Il servizio invia un messaggio di risposta che contiene il nuovo valore ETag per la raccolta di proprietà dichiarate sull'argomento $iothub/twin/res/{status}/?$rid={request id}.The service then sends a response message that contains the new ETag value for the reported properties collection on topic $iothub/twin/res/{status}/?$rid={request id}. Questo messaggio di risposta usa lo stesso request ID della richiesta.This response message uses the same request ID as the request.

Il corpo del messaggio di richiesta include un documento JSON che contiene nuovi valori per le proprietà segnalate.The request message body contains a JSON document, that contains new values for reported properties. Ogni membro nel documento JSON aggiorna o aggiunge il membro corrispondente nel documento del dispositivo gemello.Each member in the JSON document updates or add the corresponding member in the device twin’s document. Un membro impostato su null elimina il membro dall'oggetto contenitore.A member set to null, deletes the member from the containing object. Ad esempio: For example:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

I possibili codici di stato sono i seguenti:The possible status codes are:

StatusStatus DESCRIZIONEDescription
200200 SuccessSuccess
400400 Richiesta non valida.Bad Request. JSON non validoMalformed JSON
429429 Numero eccessivo di richieste (limitazione), come descritto in Limitazione dell'hub IoTToo many requests (throttled), as per IoT Hub throttling
55 Errori serverServer errors

Per altre informazioni, vedere la Guida per gli sviluppatori sui dispositivi gemelli.For more information, see Device twins developer's guide.

Ricezione delle notifiche di aggiornamento delle proprietà desiderateReceiving desired properties update notifications

Quando un dispositivo è connesso, l'hub IoT invia notifiche all'argomento $iothub/twin/PATCH/properties/desired/?$version={new version}, con il contenuto dell'aggiornamento eseguito dal back-end della soluzione.When a device is connected, IoT Hub sends notifications to the topic $iothub/twin/PATCH/properties/desired/?$version={new version}, which contain the content of the update performed by the solution back end. Ad esempio: For example:

{
    "telemetrySendFrequency": "5m",
    "route": null
}

Come per gli aggiornamenti delle proprietà, i valori null indicano l'eliminazione del membro dell'oggetto JSON.As for property updates, null values means that the JSON object member is being deleted.

Importante

L'hub IoT genera notifiche di modifica solo quando i dispositivi sono connessi.IoT Hub generates change notifications only when devices are connected. Assicurarsi di implementare il flusso di riconnessione del dispositivo per mantenere la sincronizzazione delle proprietà desiderate tra l'hub IoT e l'app per dispositivo.Make sure to implement the device reconnection flow to keep the desired properties synchronized between IoT Hub and the device app.

Per altre informazioni, vedere la Guida per gli sviluppatori sui dispositivi gemelli.For more information, see Device twins developer's guide.

Rispondere a un metodo direttoRespond to a direct method

Un dispositivo deve effettuare la sottoscrizione a $iothub/methods/POST/#.First, a device has to subscribe to $iothub/methods/POST/#. L'hub IoT invia le richieste di metodo all'argomento $iothub/methods/POST/{method name}/?$rid={request id} con un codice JSON valido o un corpo vuoto.IoT Hub sends method requests to the topic $iothub/methods/POST/{method name}/?$rid={request id}, with either a valid JSON or an empty body.

Per rispondere, il dispositivo invia un messaggio con un codice JSON valido o un corpo vuoto all'argomento $iothub/methods/res/{status}/?$rid={request id}.To respond, the device sends a message with a valid JSON or empty body to the topic $iothub/methods/res/{status}/?$rid={request id}. In questo messaggio, l'ID della richiesta deve corrispondere a quello nel messaggio della richiesta, e lo stato deve essere un numero intero.In this message, the request ID must match the one in the request message, and status must be an integer.

Per altre informazioni, vedere la Guida per gli sviluppatori sui metodi diretti.For more information, see Direct method developer's guide.

Ulteriori considerazioniAdditional considerations

Come considerazione finale, se è necessario personalizzare il comportamento del protocollo MQTT sul lato cloud, occorre rivedere il gateway del protocollo IoT di Azure.As a final consideration, if you need to customize the MQTT protocol behavior on the cloud side, you should review the Azure IoT protocol gateway. Questo software consente di distribuire un gateway di protocollo personalizzato ad alte prestazioni che si interfaccia direttamente con l'hub IoT.This software enables you to deploy a high-performance custom protocol gateway that interfaces directly with IoT Hub. Il gateway del protocollo IoT Azure consente di personalizzare il protocollo del dispositivo per supportare le distribuzioni di MQTT cosiddette "brownfield" o altri protocolli personalizzati.The Azure IoT protocol gateway enables you to customize the device protocol to accommodate brownfield MQTT deployments or other custom protocols. Questo approccio richiede tuttavia l'esecuzione e la gestione di un gateway di protocollo personalizzato.This approach does require, however, that you run and operate a custom protocol gateway.

Passaggi successiviNext steps

Per altre informazioni sul protocollo MQTT, vedere la documentazione di MQTT.To learn more about the MQTT protocol, see the MQTT documentation.

Per altre informazioni sulla pianificazione della distribuzione dell'hub IoT, vedere:To learn more about planning your IoT Hub deployment, see:

Per altre informazioni sulle funzionalità dell'hub IoT, vedere:To further explore the capabilities of IoT Hub, see: