Inviare messaggi da cloud a dispositivo con l'hub IoT (.NET)
L'hub IoT di Azure è un servizio completamente gestito che consente di abilitare comunicazioni bidirezionali affidabili e sicure tra milioni di dispositivi e un back-end della soluzione.
Questo articolo illustra come:
Inviare messaggi da cloud a dispositivo (C2D) dal back-end della soluzione a un singolo dispositivo tramite hub IoT
Ricevere messaggi da cloud a dispositivo in un dispositivo
Richiedere il riconoscimento di recapito (feedback), dal back-end della soluzione, per i messaggi inviati a un dispositivo da hub IoT
Nota
Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT standard e standard, vedere Scegliere il livello di hub IoT appropriato per la soluzione.
Alla fine di questo articolo si eseguono due app console .NET.
MessageReceiveSample: un'app del dispositivo di esempio inclusa in Microsoft Azure IoT SDK per .NET, che si connette all'hub IoT e riceve messaggi da cloud a dispositivo.
SendCloudToDevice: un'app di servizio che invia un messaggio da cloud a dispositivo all'app per dispositivi tramite hub IoT e quindi riceve il riconoscimento del recapito.
Nota
hub IoT offre il supporto SDK per molte piattaforme e linguaggi per dispositivi (C, Java, Python e JavaScript) tramite AZURE IoT SDK per dispositivi.
Altre informazioni sui messaggi da cloud a dispositivo sono disponibili in Messaggistica da dispositivo a cloud e da cloud a dispositivo con l'hub IoT.
Prerequisiti
Una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Un hub IoT nella sottoscrizione di Azure. Se non si ha ancora un hub, è possibile seguire la procedura descritta in Creare un hub IoT.
Un dispositivo registrato nell'hub IoT. Se non è ancora stato registrato un dispositivo, registrare un dispositivo nel portale di Azure.
Questo articolo usa il codice di esempio di Azure IoT SDK per C#.
- Scaricare o clonare il repository SDK da GitHub nel computer di sviluppo.
- Assicurarsi che .NET Core 3.0.0 o versione successiva sia installato nel computer di sviluppo. Controllare la versione eseguendo
dotnet --versione scaricare .NET , se necessario.
Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).
Visual Studio.
Ottenere la stringa di connessione del dispositivo
In questo articolo viene eseguita un'app di esempio che simula un dispositivo, che riceve messaggi da cloud a dispositivo inviati tramite il hub IoT. L'app di esempio MessageReceiveSample inclusa in Microsoft Azure IoT SDK per .NET si connette all'hub IoT e funge da dispositivo simulato. L'esempio usa la stringa di connessione primaria del dispositivo registrato nell'hub IoT.
Per ottenere la stringa di connessione primaria per un dispositivo registrato nell'hub IoT, seguire questa procedura:
Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro a sinistra dell'hub IoT, in Gestione dispositivi selezionare Dispositivi.
Nell'elenco dei dispositivi selezionare il dispositivo appropriato.
Copiare la stringa di connessione primaria e salvare il valore.
Ricevere messaggi nell'app per dispositivi
In questa sezione eseguire l'app del dispositivo di esempio MessageReceiveSample per ricevere messaggi C2D inviati tramite l'hub IoT. Aprire un nuovo prompt dei comandi e passare alla cartella azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample , nella cartella in cui è stato espanso Azure IoT C# SDK. Eseguire i comandi seguenti, sostituendo il {Your device connection string} valore segnaposto con la stringa di connessione del dispositivo copiata dal dispositivo registrato nell'hub IoT.
dotnet restore
dotnet run --c "{Your device connection string}"
L'output seguente proviene dall'app del dispositivo di esempio dopo l'avvio e la connessione all'hub IoT:
5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
L'app del dispositivo di esempio esegue il polling dei messaggi usando i metodi ReceiveAsync e CompleteAsync . Il ReceiveC2dMessagesPollingAndCompleteAsync metodo usa il ReceiveAsync metodo , che restituisce in modo asincrono il messaggio ricevuto al momento in cui il dispositivo riceve il messaggio. ReceiveAsync restituisce Null dopo un periodo di timeout specificabile. In questo esempio viene usato il valore predefinito di un minuto. Quando il dispositivo riceve un valore Null, deve continuare ad attendere nuovi messaggi. Questo requisito è il motivo per cui l'app di esempio include il blocco di codice seguente nel ReceiveC2dMessagesPollingAndCompleteAsync metodo :
if (receivedMessage == null)
{
continue;
}
La chiamata al CompleteAsync metodo notifica hub IoT che il messaggio è stato elaborato correttamente e che il messaggio può essere rimosso in modo sicuro dalla coda del dispositivo. Il dispositivo deve chiamare questo metodo quando l'elaborazione viene completata correttamente indipendentemente dal protocollo in uso.
Con i protocolli AMQP e HTTPS, ma non con il protocollo MQTT, il dispositivo può anche:
- Abbandonare un messaggio, che comporta hub IoT conservare il messaggio nella coda del dispositivo per un utilizzo futuro.
- Rifiutare un messaggio, che rimuove definitivamente il messaggio dalla coda del dispositivo.
Se si verifica un evento che impedisce al dispositivo di completare, abbandonare o rifiutare il messaggio, hub IoT, dopo un periodo di timeout fisso, accoda nuovamente il messaggio per il recapito. Per questo motivo, la logica di elaborazione dei messaggi nell'app per dispositivo deve essere idempotente, in modo che la ricezione dello stesso messaggio più volte produa lo stesso risultato.
Per altre informazioni sul ciclo di vita dei messaggi da cloud a dispositivo e su come hub IoT elabora i messaggi da cloud a dispositivo, vedere Inviare messaggi da cloud a dispositivo da un hub IoT.
Nota
Quando si usa HTTPS invece di MQTT o AMQP come trasporto, il metodo ReceiveAsync verrà restituito immediatamente. Il modello supportato per i messaggi da cloud a dispositivo con HTTPS è dispositivi connessi a intermittenza che controllano raramente i messaggi (almeno ogni 25 minuti). La generazione di altre ricezioni HTTPS comporta la limitazione delle richieste da parte dell'hub IoT. Per altre informazioni sulle differenze tra il supporto di MQTT, AMQP e HTTPS, vedere Linee guida sulle comunicazioni da cloud a dispositivo e Scegliere un protocollo di comunicazione.
Ottenere la stringa di connessione dell'hub IoT
In questo articolo viene creato un servizio back-end per inviare messaggi da cloud a dispositivo tramite il hub IoT. Per inviare messaggi da cloud a dispositivo, è necessario che il servizio disponga dell'autorizzazione di connessione al servizio. Per impostazione predefinita, ogni hub IoT viene creato con un servizio con nome di criteri di accesso condiviso che concede tale autorizzazione.
Per ottenere la stringa di connessione dell'hub IoT per i criteri del servizio, seguire questa procedura:
Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro sinistro dell'hub IoT selezionare Criteri di accesso condiviso.
Dall'elenco dei criteri selezionare i criteri del servizio.
Copiare la stringa di connessione primaria e salvare il valore.
Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.
Inviare un messaggio da cloud a dispositivo
In questa sezione viene creata un'app console .NET che invia messaggi da cloud a dispositivo all'app per dispositivi simulati. È necessario l'ID dispositivo dal dispositivo e la stringa di connessione dell'hub IoT.
In Visual Studio selezionare File>Nuovo>Progetto. In Crea un nuovo progetto, selezionare App console (.NET Framework) , quindi selezionare Avanti.
Assegnare al progetto il nome SendCloudToDevice e quindi selezionare Avanti.
Accettare la versione più recente di .NET Framework. Selezionare Crea per creare il progetto.
In Esplora soluzioni fare clic con il pulsante destro del mouse sul nuovo progetto e quindi scegliere Gestisci pacchetti NuGet.
In Gestisci pacchetti NuGet selezionare Sfoglia e cercare e selezionare Microsoft.Azure.Devices. Selezionare Installa.
In questo passaggio verrà quindi scaricato e installato il pacchetto NuGet Azure IoT Service SDK e verrà aggiunto un riferimento a tale pacchetto.
Aggiungere l'istruzione
usingseguente all'inizio del file Program.cs.using Microsoft.Azure.Devices;Aggiungere i campi seguenti alla classe Program . Sostituire il
{iot hub connection string}valore segnaposto con la stringa di connessione dell'hub IoT annotata in precedenza in Ottenere la stringa di connessione dell'hub IoT. Sostituire il{device id}valore segnaposto con l'ID dispositivo del dispositivo registrato nell'hub IoT.static ServiceClient serviceClient; static string connectionString = "{iot hub connection string}"; static string targetDevice = "{device id}";Aggiungere il metodo seguente alla classe Program per inviare un messaggio al dispositivo.
private async static Task SendCloudToDeviceMessageAsync() { var commandMessage = new Message(Encoding.ASCII.GetBytes("Cloud to device message.")); await serviceClient.SendAsync(targetDevice, commandMessage); }Aggiungere infine le righe seguenti al metodo Main .
Console.WriteLine("Send Cloud-to-Device message\n"); serviceClient = ServiceClient.CreateFromConnectionString(connectionString); Console.WriteLine("Press any key to send a C2D message."); Console.ReadLine(); SendCloudToDeviceMessageAsync().Wait(); Console.ReadLine();Premere F5 per avviare l'app del servizio di esempio. Selezionare la finestra SendCloudToDevice e premere INVIO. Verrà visualizzato il messaggio ricevuto dall'app del dispositivo di esempio, come illustrato nell'esempio di output seguente.
5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample. 5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub... 5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device. 5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase. 5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id= 5/22/2023 11:15:18 AM> Received message: [Cloud to device message.] Content type: 5/22/2023 11:15:18 AM> Completed C2D message with Id=.
Ricevere feedback di recapito
È possibile richiedere riconoscimenti di recapito (o scadenza) da hub IoT per ogni messaggio da cloud a dispositivo. Questa opzione consente al back-end della soluzione di informare, ripetere o compensare facilmente la logica. Per altre informazioni sul feedback dei messaggi da cloud a dispositivo, vedere Messaggistica da dispositivo a cloud e da cloud a dispositivo con l'hub IoT.
In questa sezione si modifica l'app del servizio di esempio SendCloudToDevice per richiedere commenti e suggerimenti e riceverla dall'hub IoT.
In Visual Studio, nel progetto SendCloudToDevice aggiungere il seguente metodo alla classe Programma.
private async static void ReceiveFeedbackAsync() { var feedbackReceiver = serviceClient.GetFeedbackReceiver(); Console.WriteLine("\nReceiving c2d feedback from service"); while (true) { var feedbackBatch = await feedbackReceiver.ReceiveAsync(); if (feedbackBatch == null) continue; Console.ForegroundColor = ConsoleColor.Yellow; Console.WriteLine("Received feedback: {0}", string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode))); Console.ResetColor(); await feedbackReceiver.CompleteAsync(feedbackBatch); } }Si noti che il modello di ricezione è identico a quello usato per ricevere messaggi da cloud a dispositivo dall'app per dispositivo.
Aggiungere la riga seguente nel metodo Main immediatamente dopo
serviceClient = ServiceClient.CreateFromConnectionString(connectionString).ReceiveFeedbackAsync();Per richiedere feedback del recapito del messaggio da cloud a dispositivo, è necessario specificare una proprietà nel metodo SendCloudToDeviceMessageAsync . Aggiungere la riga seguente, subito dopo la riga
var commandMessage = new Message(...);.commandMessage.Ack = DeliveryAcknowledgement.Full;Assicurarsi che l'app del dispositivo di esempio sia in esecuzione e quindi eseguire l'app del servizio di esempio premendo F5. Selezionare la finestra della console SendCloudToDevice e premere INVIO. Dovrebbe essere visualizzato il messaggio ricevuto dall'app del dispositivo di esempio e, dopo alcuni secondi, il messaggio di feedback ricevuto dall'applicazione SendCloudToDevice . L'output seguente mostra il messaggio di feedback ricevuto dall'app del servizio di esempio:
Send Cloud-to-Device message Receiving c2d feedback from service Press any key to send a C2D message. Received feedback: Success
Nota
Per semplicità, questo articolo non implementa criteri di ripetizione dei tentativi. Nel codice di produzione è consigliabile implementare criteri di ripetizione dei tentativi, ad esempio un backoff esponenziale, come suggerito in Gestione degli errori temporanei.
Passaggi successivi
In questo articolo si è appreso come inviare e ricevere messaggi da cloud a dispositivo.
Per altre informazioni sui messaggi da cloud a dispositivo, vedere Inviare messaggi da cloud a dispositivo da un hub IoT.
Per altre informazioni sui formati di messaggio di hub IoT, vedere Creare e leggere hub IoT messaggi.