Esercitazione: Distribuire Funzioni di Azure come moduli IoT Edge

Si applica a: IoT Edge 1.5 IoT Edge 1.4

È possibile usare Funzioni di Azure per distribuire il codice che implementa la logica di business direttamente nei dispositivi Azure IoT Edge. Questa esercitazione illustra la creazione e la distribuzione di una funzione di Azure che filtra i dati del sensore nel dispositivo IoT Edge simulato. Viene usato il dispositivo IoT Edge simulato creato nelle guide introduttive. In questa esercitazione apprenderai a:

La funzione di Azure creata in questa esercitazione filtra i dati relativi alla temperatura generati dal dispositivo. Questa funzione invia messaggi upstream all'hub IoT di Azure solo quando la temperatura è superiore a una soglia specificata.

Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.

Prerequisiti

Prima di iniziare questa esercitazione, eseguire l'esercitazione per configurare l'ambiente di sviluppo per lo sviluppo di contenitori Linux: Sviluppare moduli Azure IoT Edge usando Visual Studio Code. Dopo aver completato questa esercitazione, saranno soddisfatti i prerequisiti seguenti:

• Un hub IoT di livello Gratuito o Standard in Azure.
• Un dispositivo AMD64 che esegue Azure IoT Edge con contenitori Linux. È possibile usare la guida introduttiva per configurare un dispositivo Linux o un dispositivo Windows.
• Un registro contenitori, ad esempio Registro Azure Container.
• Visual Studio Code configurato con le estensioni Azure IoT Edge e hub IoT di Azure. L'estensione Azure IoT Edge Tools per Visual Studio Code è in modalità manutenzione.
• Scaricare e installare un sistema di gestione contenitori compatibile con Docker nel computer di sviluppo. Configurarlo per l'esecuzione di contenitori Linux.

Per sviluppare un modulo IoT Edge con Funzioni di Azure, installare i prerequisiti aggiuntivi nel computer di sviluppo:

• Estensione C# per Visual Studio Code con tecnologia OmniSharp.
• .NET Core SDK 3.1.

Creare un progetto per le funzioni

Azure IoT Edge per Visual Studio Code installato nei prerequisiti fornisce funzionalità di gestione e alcuni modelli di codice. In questa sezione si usa Visual Studio Code per creare una soluzione IoT Edge contenente una funzione di Azure.

Crea un nuovo progetto

Seguire questa procedura per creare un modello di soluzione funzione C# personalizzabile.

1. Aprire Visual Studio Code nel computer di sviluppo.

2. In Visual Studio Code aprire il riquadro comandi selezionando Visualizza>Riquadro comandi.

3. Nel riquadro comandi aggiungere ed eseguire il comando Azure IoT Edge: New IoT Edge solution (Azure IoT Edge: Nuova soluzione IoT Edge). Seguire questi prompt nel riquadro comandi per creare la soluzione:

   • Selezionare una cartella: scegliere il percorso nel computer di sviluppo per Visual Studio Code per creare i file della soluzione.
   • Specificare un nome di soluzione: aggiungere un nome descrittivo per la soluzione, ad esempio FunctionSolution o accettare il valore predefinito.|
   • Selezionare un modello di modulo: scegliere Funzioni di Azure - C#.
   • Specificare un nome di modulo | Assegnare al modulo il nome CSharpFunction.
   • Specificare un repository di immagini Docker per il modulo. Un repository di immagini include il nome del registro contenitori e il nome dell'immagine del contenitore. L'immagine del contenitore è prepopolata dall'ultimo passaggio. Sostituire localhost:5000 con il valore di Server di accesso del registro contenitori di Azure. È possibile recuperare il server di accesso dalla pagina di panoramica del registro contenitori nel portale di Azure. La stringa finale è simile a <nome registro>.azurecr.io/csharpfunction.

   

Aggiungere le credenziali del registro

Il file dell'ambiente della soluzione archivia le credenziali per il registro contenitori e le condivide con il runtime IoT Edge. Queste credenziali sono necessarie al runtime per eseguire il pull delle immagini private nel dispositivo IoT Edge.

L'estensione IoT Edge in Visual Studio Code cerca di eseguire il pull delle credenziali del Registro Container da Azure, per inserirle nel file di ambiente. Verificare se le credenziali sono già nel file. In caso contrario, aggiungerle:

1. Nello strumento di esplorazione di Visual Studio Code aprire il file .env.
2. Aggiornare i campi con i valori di nome utente e password copiati dal Registro Azure Container. È possibile trovarli di nuovo passando al registro contenitori in Azure e cercando la pagina Impostazioni>Chiavi di accesso.
3. Fare clic su Salva per salvare il file.

Impostare l'architettura di destinazione su AMD64

L'esecuzione di moduli di Funzioni di Azure in IoT Edge è supportata solo nei contenitori basati su Linux AMD64. L'architettura di destinazione predefinita per Visual Studio Code è Linux AMD64, ma è stata impostata in modo esplicito su Linux AMD64 qui.

1. Aprire il riquadro comandi e cercare Azure IoT Edge: Impostare la piattaforma di destinazione predefinita per la soluzione Edge.

2. Nel riquadro comandi selezionare l'architettura di destinazione AMD64 nell'elenco di opzioni.

Aggiornare il modulo con il codice personalizzato

Aggiungere ora codice aggiuntivo in modo che il modulo CSharpFunction elabori i messaggi al perimetro prima di inoltrarli all'hub IoT.

1. Nello strumento di esplorazione di Visual Studio Code aprire modules>CSharpFunction>CSharpFunction.cs.

2. Sostituire il contenuto del file CSharpFunction.cs con il codice seguente. Questo codice riceve dati di telemetria sulla temperatura dell'ambiente e del computer e inoltra il messaggio all'hub IoT solo se la temperatura del computer supera una soglia definita.

   using System;
   using System.Collections.Generic;
   using System.IO;
   using System.Text;
   using System.Threading.Tasks;
   using Microsoft.Azure.Devices.Client;
   using Microsoft.Azure.WebJobs;
   using Microsoft.Azure.WebJobs.Extensions.EdgeHub;
   using Microsoft.Azure.WebJobs.Host;
   using Microsoft.Extensions.Logging;
   using Newtonsoft.Json;
   
   namespace Functions.Samples
   {
       public static class CSharpFunction
       {
           [FunctionName("CSharpFunction")]
           public static async Task FilterMessageAndSendMessage(
               [EdgeHubTrigger("input1")] Message messageReceived,
               [EdgeHub(OutputName = "output1")] IAsyncCollector<Message> output,
               ILogger logger)
           {
               const int temperatureThreshold = 20;
               byte[] messageBytes = messageReceived.GetBytes();
               var messageString = System.Text.Encoding.UTF8.GetString(messageBytes);
   
               if (!string.IsNullOrEmpty(messageString))
               {
                   logger.LogInformation("Info: Received one non-empty message");
                   // Get the body of the message and deserialize it.
                   var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);
   
                   if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
                   {
                       // Send the message to the output as the temperature value is greater than the threshold.
                       using (var filteredMessage = new Message(messageBytes))
                       {
                            // Copy the properties of the original message into the new Message object.
                            foreach (KeyValuePair<string, string> prop in messageReceived.Properties)
                            {filteredMessage.Properties.Add(prop.Key, prop.Value);}
                            // Add a new property to the message to indicate it is an alert.
                            filteredMessage.Properties.Add("MessageType", "Alert");
                            // Send the message.
                            await output.AddAsync(filteredMessage);
                            logger.LogInformation("Info: Received and transferred a message with temperature above the threshold");
                       }
                   }
               }
           }
       }
       //Define the expected schema for the body of incoming messages.
       class MessageBody
       {
           public Machine machine {get; set;}
           public Ambient ambient {get; set;}
           public string timeCreated {get; set;}
       }
       class Machine
       {
           public double temperature {get; set;}
           public double pressure {get; set;}
       }
       class Ambient
       {
           public double temperature {get; set;}
           public int humidity {get; set;}
       }
   }
   

3. Salvare il file.

Eseguire la compilazione e il push della soluzione IoT Edge

Nella sezione precedente è creata una soluzione IoT Edge ed è stato modificato l'oggetto CSharpFunction per filtrare i messaggi in cui la temperatura del computer segnalata è inferiore alla soglia accettabile. È ora necessario compilare la soluzione come immagine del contenitore ed eseguirne il push nel registro contenitori.

1. Aprire il terminale integrato di Visual Studio Code selezionando Visualizza>Terminale.

2. Accedere a Docker immettendo il comando seguente nel terminale. Accedere con il nome utente, la password e il server di accesso del Registro Azure Container. È possibile recuperare questi valori dalla sezione Chiavi di accesso del registro nel portale di Azure.

   docker login -u <ACR username> -p <ACR password> <ACR login server>
   

   Potrebbe venire visualizzato un avviso di sicurezza in cui si consiglia l'uso di --password-stdin. Sebbene si tratti di una procedura consigliata per gli scenari di produzione, esula dell'ambito di questa esercitazione. Per altri dettagli, vedere le informazioni di riferimento sull'accesso a Docker.

3. Nello strumento di esplorazione di Visual Studio Code fare clic con il pulsante destro del mouse sul file deployment.template.json e scegliere Build and Push IoT Edge Solution (Compila ed esegui il push della soluzione IoT Edge).

   Il comando di creazione e push avvia tre operazioni. Prima di tutto, crea una nuova cartella nella soluzione denominata config che contiene il manifesto completo della distribuzione, basato sulle informazioni del modello di distribuzione e di altri file della soluzione. In secondo luogo, esegue docker build per creare l'immagine del contenitore in base al documento dockerfile appropriato per l'architettura di destinazione. Infine, esegue docker push per eseguire il push del repository di immagini nel registro contenitori.

   Questo processo può richiedere alcuni minuti quando viene eseguito per la prima volta, ma alla successiva esecuzione dei comandi avviene più rapidamente.

Visualizzare l'immagine del contenitore

Visual Studio Code genera un messaggio di conferma quando viene eseguito il push dell'immagine del contenitore nel registro contenitori. Per verificare personalmente se l'operazione ha esito positivo, è possibile visualizzare l'immagine nel registro.

1. Nel portale di Azure passare al Registro Azure Container.
2. Selezionare Servizi>Repository.
3. Il repository csharpfunction dovrebbe essere visualizzato nell'elenco. Selezionare il repository per visualizzare altri dettagli.
4. Nella sezione Tag dovrebbe essere visualizzato il tag 0.0.1-amd64. Questo tag indica la versione e la piattaforma dell'immagine che è stata compilata. Questi valori sono impostati nel file module.json nella cartella CSharpFunction.

Distribuire ed eseguire la soluzione

È possibile usare il portale di Azure per distribuire il modulo della funzione in un dispositivo IoT Edge con la stessa procedura seguita nella guida di avvio rapido. È anche possibile distribuire e monitorare i moduli da Visual Studio Code. Le sezioni seguenti usano Azure IoT Edge e l'hub IoT per Visual Studio Code elencati nei prerequisiti. Installare le estensioni ora, se non è già stato fatto.

1. Nello strumento di esplorazione di Visual Studio Code espandere Dispositivi nella sezione Azure IoT Hub (Hub IoT di Azure) per visualizzare l'elenco dei dispositivi IoT.

2. Fare clic con il pulsante destro del mouse sul nome del dispositivo IoT Edge e quindi scegliere Create Deployment for Single Device (Crea la distribuzione per un unico dispositivo).

3. Passare alla cartella della soluzione che contiene CSharpFunction. Aprire la cartella config, selezionare il file deployment.amd64.json e quindi scegliere Select Edge Deployment Manifest (Seleziona il manifesto della distribuzione di Edge).

4. Nel dispositivo espandere Moduli per visualizzare un elenco dei moduli distribuiti e in esecuzione. Selezionare il pulsante Aggiorna. Dovrebbe essere visualizzata la nuova CSharpFunction in esecuzione insieme al modulo SimulatedTemperatureSensor e a $edgeAgent e $edgeHub.

   La visualizzazione dei nuovi moduli potrebbe richiedere un po' di tempo. Il dispositivo IoT Edge deve recuperare le informazioni sulla nuova distribuzione dall'hub IoT, avviare i nuovi contenitori e quindi segnalare lo stato all'hub IoT.

   

Visualizzare i dati generati

È possibile visualizzare tutti i messaggi che arrivano all'hub IoT da tutti i dispositivi eseguendo Hub IoT di Azure: Avviare il monitoraggio dell'endpoint eventi predefinito nel riquadro comandi. Per interrompere il monitoraggio dei messaggi, eseguire il comando Hub IoT di Azure: Arrestare il monitoraggio dell'endpoint eventi predefinito nel riquadro comandi.

È anche possibile applicare un filtro alla visualizzazione per mostrare tutti i messaggi in arrivo all'hub IoT da un dispositivo specifico. Fare clic con il pulsante destro del mouse sul dispositivo nella sezione Hub IoT di Azure>Dispositivi dello strumento di esplorazione di Visual Studio Code e selezionare Avvia monitoraggio endpoint eventi predefinito.

Pulire le risorse

Se si intende continuare con il prossimo articolo consigliato, è possibile conservare le risorse e le configurazioni create e riutilizzarle. È anche possibile continuare a usare lo stesso dispositivo IoT Edge come dispositivo di test.

In caso contrario, è possibile eliminare le risorse di Azure e le configurazioni locali create in questo articolo per evitare addebiti.

Eliminare le risorse di Azure

L'eliminazione delle risorse e dei gruppi di risorse di Azure è irreversibile. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate. Se l'hub IoT è stato creato all'interno di un gruppo di risorse esistente che contiene risorse che si vogliono conservare, eliminare solo la risorsa hub IoT stessa, invece dell'intero gruppo.

Per eliminare le risorse:

1. Accedere al portale di Azure e selezionare Gruppi di risorse.

2. Selezionare il nome del gruppo di risorse contenente le risorse di test di IoT Edge.

3. Esaminare l'elenco delle risorse contenute nel gruppo di risorse. Per eliminarle tutte, è possibile selezionare Elimina gruppo di risorse. Se se ne vogliono eliminare solo alcune, è possibile selezionare ogni risorsa per eliminarle singolarmente.

Passaggi successivi

In questa esercitazione è stato creato un modulo di funzione di Azure con codice per filtrare i dati non elaborati generati dal dispositivo IoT Edge.

Continuare con le esercitazioni successive per ottenere informazioni sugli altri modi in cui Azure IoT Edge può contribuire alla trasformazione dei dati in informazioni dettagliate aziendali nei dispositivi perimetrali.