Tutorial: Implantar o Azure Functions como módulos do IoT Edge

Artigo
04/11/2024

Aplica-se a: IoT Edge 1.4

Importante

O IoT Edge 1.4 é a versão suportada. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

Pode utilizar as Funções do Azure para implementar código que aplica a sua lógica de negócio diretamente nos seus dispositivos Azure IoT Edge. Este tutorial orienta você na criação e implantação de uma Função do Azure que filtra dados do sensor no dispositivo IoT Edge simulado. Você usa o dispositivo IoT Edge simulado que criou nos inícios rápidos. Neste tutorial, irá aprender a:

Use o Visual Studio Code para criar uma função do Azure.
Use o Visual Studio Code e o Docker para criar uma imagem do Docker e publicá-la em um registro de contêiner.
Implementar o módulo a partir do registo de contentor no seu dispositivo IoT Edge.
Ver dados filtrados.

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

A Função do Azure que você cria neste tutorial filtra os dados de temperatura gerados pelo seu dispositivo. A Função só envia mensagens upstream para o Hub IoT do Azure quando a temperatura está acima de um limite especificado.

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Antes de começar este tutorial, faça o tutorial para configurar seu ambiente de desenvolvimento para desenvolvimento de contêineres Linux: Desenvolver módulos do Azure IoT Edge usando o Visual Studio Code. Depois de concluir esse tutorial, você deve ter os seguintes pré-requisitos em vigor:

Um Hub IoT no escalão gratuito ou standard no Azure.
Um dispositivo AMD64 executando o Azure IoT Edge com contêineres Linux. Você pode usar o início rápido para configurar um dispositivo Linux ou um dispositivo Windows.
Um registro de contêiner, como o Azure Container Registry.
Código do Visual Studio configurado com as extensões Azure IoT Edge e Azure IoT Hub . A extensão de código das ferramentas do Azure IoT Edge para Visual Studio está no modo de manutenção.
Baixe e instale um sistema de gerenciamento de contêineres compatível com Docker em sua máquina de desenvolvimento. Configure-o para executar contêineres Linux.

Para desenvolver um módulo IoT Edge com o Azure Functions, instale pré-requisitos adicionais em sua máquina de desenvolvimento:

Criar um projeto de função

O Azure IoT Edge para Visual Studio Code que você instalou nos pré-requisitos fornece recursos de gerenciamento, bem como alguns modelos de código. Nesta seção, você usa o Visual Studio Code para criar uma solução IoT Edge que contém uma Função do Azure.

Criar um novo projeto

Siga estas etapas para criar um modelo de solução de função C# que seja personalizável.

Abra o Visual Studio Code no computador de desenvolvimento.
Abra a paleta de comandos Código do Visual Studio selecionando Exibir>paleta de comandos.
Na paleta de comandos, adicione e execute o comando Azure IoT Edge: Nova solução IoT Edge. Siga estes prompts na paleta de comandos para criar sua solução:
- Selecione uma pasta: escolha o local em sua máquina de desenvolvimento para o Visual Studio Code para criar os arquivos de solução.
- Forneça um nome de solução: adicione um nome descritivo para sua solução, como FunctionSolution, ou aceite o padrão.|
- Selecione um modelo de módulo: escolha Azure Functions - C#.
- Forneça um nome de módulo | Nomeie seu módulo CSharpFunction.
- Forneça um repositório de imagens do Docker para o módulo. Os repositórios de imagens incluem o nome do seu registo de contentor e o nome da sua imagem de contentor. Sua imagem de contêiner é pré-preenchida a partir da última etapa. Substitua localhost:5000 pelo valor do servidor de Logon do seu registro de contêiner do Azure. Você pode recuperar o servidor de Logon na página Visão geral do seu registro de contêiner no portal do Azure. A cadeia final é semelhante a <nome do registo>.azurecr.io/csharpfunction.

Adicionar as credenciais do registo

O arquivo de ambiente da sua solução armazena as credenciais para o registro do contêiner e as compartilha com o tempo de execução do IoT Edge. O tempo de execução precisa dessas credenciais para extrair suas imagens privadas para o dispositivo IoT Edge.

A extensão IoT Edge no Visual Studio Code tenta extrair suas credenciais de registro de contêiner do Azure e preenchê-las no arquivo de ambiente. Verifique se as suas credenciais já estão no ficheiro. Se não, adicione-os agora:

No explorador de código do Visual Studio, abra o .env arquivo.
Atualize os campos com os valores nome de utilizador e palavra-passe que copiou do seu Azure Container Registry. Você pode encontrá-los novamente acessando seu registro de contêiner no Azure e procurando na página Configurações>de chaves de acesso.
Guarde este ficheiro.

Nota

Este tutorial usa credenciais de logon de administrador para o Registro de Contêiner do Azure, que são convenientes para cenários de desenvolvimento e teste. Quando estiver pronto para cenários de produção, recomendamos uma opção de autenticação de privilégios mínimos, como entidades de serviço. Para obter mais informações, consulte Gerenciar o acesso ao registro de contêiner.

Definir arquitetura de destino como AMD64

A execução de módulos do Azure Functions no IoT Edge é suportada apenas em contêineres baseados em Linux AMD64. A arquitetura de destino padrão para o Visual Studio Code é Linux AMD64, mas vamos defini-la explicitamente para Linux AMD64 aqui.

Abra a paleta de comandos e procure Azure IoT Edge: Definir Plataforma de Destino Padrão para Solução de Borda.
Na paleta de comandos, selecione a arquitetura de destino AMD64 na lista de opções.

Atualizar o módulo com o código personalizado

Vamos adicionar algum código adicional para que seu módulo CSharpFunction processe as mensagens na borda antes de encaminhá-las para o Hub IoT.

No explorador de código do Visual Studio, abra os módulos>CSharpFunction>CSharpFunction.cs.

Substitua o conteúdo do arquivo CSharpFunction.cs pelo código a seguir. Esse código recebe telemetria sobre temperatura ambiente e da máquina e só encaminha a mensagem para o Hub IoT se a temperatura da máquina estiver acima de um limite definido.

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

Guarde o ficheiro.

Crie e envie sua solução IoT Edge

Na seção anterior, você criou uma solução IoT Edge e modificou o CSharpFunction para filtrar mensagens com temperaturas de máquina relatadas abaixo do limite aceitável. Agora, tem de criar a solução como uma imagem de contentor e enviá-la para o registo de contentor.

Abra o terminal integrado do Visual Studio Code selecionando View>Terminal.
Faça login no Docker inserindo o seguinte comando no terminal. Entre com o nome de usuário, a senha e o servidor de logon do seu registro de contêiner do Azure. Você pode recuperar esses valores na seção Chaves de acesso do seu registro no portal do Azure.
```
docker login -u <ACR username> -p <ACR password> <ACR login server>
```
Poderá receber um aviso de segurança a recomendar a utilização do --password-stdin. Embora essa prática recomendada seja recomendada para cenários de produção, ela está fora do escopo deste tutorial. Para obter mais informações, consulte a referência de login do docker.
No explorador de código do Visual Studio, clique com o botão direito do mouse no arquivo de deployment.template.json e selecione Criar e enviar solução IoT Edge.

O comando build e push inicia três operações. Primeiro, ele cria uma nova pasta na solução chamada config que contém o manifesto de implantação completo, que é criado a partir de informações no modelo de implantação e outros arquivos de solução. Em segundo lugar, ele é executado docker build para criar a imagem do contêiner com base no dockerfile apropriado para sua arquitetura de destino. Em seguida, ele é executado docker push para enviar o repositório de imagens para o registro do contêiner.

Esse processo pode levar vários minutos na primeira vez, mas é mais rápido na próxima vez que você executar os comandos.

Ver a imagem de contentor

O Visual Studio Code apresenta uma mensagem de êxito quando a imagem de contentor é enviada para o seu registo de contentor. Se quiser confirmar a operação bem-sucedida, pode ver a imagem no registo.

No portal do Azure, procure o registo de contentor do Azure.
Selecione Repositórios de Serviços>.
Deverá ver o repositório csharpfunction na lista. Selecione este repositório para ver mais detalhes.
Na secção Etiquetas, deverá ver a etiqueta 0.0.1-amd64. Esta etiqueta indica a versão e a plataforma da imagem criada. Estes valores estão definidos no ficheiro module.json na pasta CSharpFunction.

Implementar e executar a solução

Você pode usar o portal do Azure para implantar seu módulo Function em um dispositivo IoT Edge como fez no início rápido. Também pode implementar e monitorizar os módulos a partir do Visual Studio Code. As seções a seguir usam o Azure IoT Edge e o Hub IoT para Visual Studio Code que foi listado nos pré-requisitos. Instale as extensões agora, se ainda não o fez.

No explorador de código do Visual Studio, na seção Hub IoT do Azure, expanda Dispositivos para ver sua lista de dispositivos IoT.
Clique com o botão direito do mouse no nome do seu dispositivo IoT Edge e selecione Criar implantação para um único dispositivo.
Procure a pasta de solução que contém a CSharpFunction. Abra a pasta config, selecione o arquivo deployment.amd64.json e escolha Select Edge Deployment Manifest.
No dispositivo, expanda Módulos para ver uma lista de módulos implantados e em execução. Clique no botão Atualizar. Você deve ver o novo CSharpFunction em execução junto com o módulo SimulatedTemperatureSensor e o $edgeAgent e $edgeHub.

Pode levar alguns momentos para que os novos módulos apareçam. Seu dispositivo IoT Edge precisa recuperar suas novas informações de implantação do Hub IoT, iniciar os novos contêineres e, em seguida, relatar o status de volta ao Hub IoT.

Ver os dados gerados

Você pode ver todas as mensagens que chegam ao seu hub IoT de todos os seus dispositivos executando o Hub IoT do Azure: Start Monitoring Built-in Event Endpoint na paleta de comandos. Para parar de monitorar mensagens, execute o comando Azure IoT Hub: Stop Monitoring Built-in Event Endpoint na paleta de comandos.

Também pode filtrar para ver todas as mensagens que chegam ao seu hub IoT a partir de um dispositivo específico. Clique com o botão direito do mouse no dispositivo na seção Dispositivos do Hub>IoT do explorador de códigos do Visual Studio e selecione Iniciar monitoramento de ponto de extremidade de evento interno.

Clean up resources (Limpar recursos)

Se planeia avançar para o próximo artigo recomendado, pode manter os recursos e as configurações que criou e reutilizá-los. Também pode continuar a utilizar o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, pode eliminar as configurações locais e os recursos do Azure que criou neste artigo para evitar custos.

Eliminar recursos do Azure

A eliminação de recursos e grupos de recursos do Azure é irreversível. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados. Se você criou o hub IoT dentro de um grupo de recursos existente que tem recursos que deseja manter, exclua apenas o recurso do hub IoT em si, não o grupo de recursos.

Para eliminar os recursos:

Inicie sessão no Portal do Azure e selecione Grupos de recursos.
Selecione o nome do grupo de recursos que contém os recursos de teste do IoT Edge.
Reveja a lista de recursos contidos no seu grupo de recursos. Se quiser eliminá-los todos, pode selecionar Eliminar grupo de recursos. Se quiser eliminar apenas alguns dos recursos, pode clicar em cada um para eliminá-los individualmente.

Próximos passos

Neste tutorial, você criou um módulo Azure Function com código para filtrar dados brutos gerados pelo seu dispositivo IoT Edge.

Continue para os próximos tutoriais para saber mais sobre outras formas em que o Azure IoT Edge o pode ajudar a transformar os dados em informações empresariais na periferia.

Localizar médias com um período flutuante no Azure Stream Analytics