Esercitazione: Distribuire Funzioni di Azure come moduli IoT Edge

Articolo
04/11/2024

Si applica a: IoT Edge 1.4

Importante

IoT Edge 1.4 è la versione supportata. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

È 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. Usare il dispositivo IoT Edge simulato creato nelle guide introduttive. In questa esercitazione apprenderai a:

Usare Visual Studio Code per creare una funzione di Azure.
Usare Visual Studio Code e Docker per creare un'immagine Docker e pubblicarla in un registro contenitori.
Distribuire il modulo dal registro contenitori al dispositivo IoT Edge.
Visualizzare i dati filtrati.

Diagram of function architecture, showing how to stage and deploy a function module.

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à di 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 prerequisiti aggiuntivi nel computer di sviluppo:

Creare un progetto per le funzioni

Azure IoT Edge per Visual Studio Code installato nei prerequisiti offre 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.

Aprire Visual Studio Code nel computer di sviluppo.
Aprire il riquadro comandi di Visual Studio Code selezionando Visualizza>riquadro comandi.
Nel riquadro comandi aggiungere ed eseguire il comando Azure IoT Edge: Nuova soluzione IoT Edge. Seguire queste istruzioni 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 viene prepopolato 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 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 di ambiente della soluzione archivia le credenziali per il registro contenitori e le condivide con il runtime di IoT Edge. Il runtime richiede queste credenziali per eseguire il pull delle immagini private nel dispositivo IoT Edge.

L'estensione IoT Edge in Visual Studio Code tenta di eseguire il pull delle credenziali del registro contenitori da Azure e di popolarle nel file di ambiente. Verificare se le credenziali sono già presenti nel file. In caso contrario, aggiungerle:

Nello strumento di esplorazione di Visual Studio Code aprire il .env file.
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 delle chiavi di Impostazioni> Access.
Fare clic su Salva per salvare il file.

Nota

Questa esercitazione usa le credenziali di accesso amministratore per Registro Azure Container, che sono utili per scenari di sviluppo e test. Quando si è pronti per gli scenari di produzione, è consigliabile usare un'opzione di autenticazione con privilegi minimi, ad esempio le entità servizio. Per altre informazioni, vedere Gestire l'accesso al registro contenitori.

Impostare l'architettura di destinazione su AMD64

L'esecuzione di moduli 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 verrà impostata in modo esplicito su Linux AMD64 qui.

Aprire il riquadro comandi e cercare Azure IoT Edge: Impostare la piattaforma di destinazione predefinita per la soluzione Edge.
Nel riquadro comandi selezionare l'architettura di destinazione AMD64 dall'elenco di opzioni.

Aggiornare il modulo con il codice personalizzato

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

Nello strumento di esplorazione di Visual Studio Code aprire i moduli>CSharpFunction>CSharpFunction.cs.

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;}
    }
}

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.

Aprire il terminale integrato di Visual Studio Code selezionando Visualizza>Terminale.
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.
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.

Nel portale di Azure passare al Registro Azure Container.
Selezionare Repository di servizi>.
Il repository csharpfunction dovrebbe essere visualizzato nell'elenco. Selezionare il repository per visualizzare altri dettagli.
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 Funzione in un dispositivo IoT Edge come illustrato nell'avvio rapido. È anche possibile distribuire e monitorare i moduli da Visual Studio Code. Le sezioni seguenti usano Azure IoT Edge e hub IoT per Visual Studio Code elencate nei prerequisiti. Installare le estensioni ora, se non è già stato fatto.

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.
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).
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).
Nel dispositivo espandere Moduli per visualizzare un elenco dei moduli distribuiti e in esecuzione. Fare clic sul 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: Avvia monitoraggio endpoint eventi predefinito nel riquadro comandi. Per interrompere il monitoraggio dei messaggi, eseguire il comando hub IoT di Azure: Arresta monitoraggio endpoint evento 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 scegliere 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:

Accedere al portale di Azure e selezionare Gruppi di risorse.
Selezionare il nome del gruppo di risorse contenente le risorse di test di IoT Edge.
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 fare clic su 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.

Trovare le medie usando una finestra mobile in Analisi di flusso di Azure