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

Artigo
06/10/2024

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Use o Azure Functions para implantar um código que implementa a lógica de negócios diretamente em seus dispositivos Azure IoT Edge. Este tutorial o orienta durante a criação e a implantação de uma Função do Azure que filtra dados do sensor em um dispositivo do IoT Edge simulado. Você usa o dispositivo IoT Edge simulado que criou nos inícios rápidos. Neste tutorial, você aprenderá como:

Usar 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.
Implantar o módulo do registro do contêiner para seu dispositivo IoT Edge.
Exibir dados filtrados.

Diagrama da arquitetura de função, mostrando como preparar e implantar um módulo de função.

A Função do Azure criada neste tutorial filtra os dados de temperatura gerados pelo seu dispositivo. Ela só envia mensagens upstream para o Hub IoT do Azure quando a temperatura estiver acima de um limite especificado.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Antes de iniciar este tutorial, faça o tutorial para configurar o ambiente de desenvolvimento para o desenvolvimento de contêiner Linux: Desenvolver módulos do Azure IoT Edge usando Visual Studio Code. Após concluir esse tutorial, você deve ter os seguintes pré-requisitos implementados:

Um Hub IoT na camada padrão ou gratuito no Azure.
Um dispositivo do AMD64 que executa 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 Registro de Contêiner do Azure.
O Visual Studio Code configurado com as extensões do Azure IoT Edge e do Hub IoT do Azure. A extensão das Ferramentas de Azure IoT Edge para Visual Studio Code está em modo de manutenção.
Baixe e instale um sistema de gerenciamento de contêiner compatível com o Docker em seu computador de desenvolvimento. Configure-o para executar contêineres do Linux.

Para desenvolver um módulo do IoT Edge com o Azure Functions, instale os pré-requisitos adicionais em seu computador de desenvolvimento:

Criar um projeto de função

O Azure IoT Edge para Visual Studio Code instalado nos pré-requisitos oferece funcionalidades de gerenciamento, bem como alguns modelos de código. Nesta seção, você pode usar o Visual Studio Code para criar uma solução de 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# personalizável.

Abra o Visual Studio Code no seu computador de desenvolvimento.
No Visual Studio Code, abra a paleta de comandos selecionando Exibir>Paleta de comandos.
Na paleta de comandos, adicione e execute o comando Azure IoT Edge: nova solução do IoT Edge. Siga estes prompts na paleta de comandos para criar sua solução:
- Selecione uma pasta: escolha o local em seu computador de desenvolvimento para o Visual Studio Code criar os arquivos da solução.
- Forneça um nome de solução: adicione um nome descritivo para a 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 o módulo CSharpFunction.
- Forneça o repositório de imagem do Docker para o módulo. Um repositório de imagem inclui o nome do registro de contêiner e o nome da imagem de contêiner. Sua imagem de contêiner foi preenchida automaticamente na ú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 da página de Visão geral do seu registro de contêiner no portal do Azure. A cadeia de caracteres final se parece com <nome do registro>.azurecr.io/csharpfunction.

Adicionar suas credenciais de registro

O arquivo do ambiente da sua solução armazena as credenciais para o registro de contêiner e as compartilha com o runtime do IoT Edge. O runtime precisa dessas credenciais para efetuar pull de imagens privadas para o seu dispositivo IoT Edge.

A extensão do IoT Edge no Visual Studio Code tenta efetuar pull de suas credenciais de Registro de Contêiner do Azure e as popula no arquivo de ambiente. Verifique se suas credenciais já estão no arquivo. Caso contrário, adicione-as agora:

No explorador do Visual Studio Code, abra o arquivo .env.
Atualize os campos com os valores de nome de usuário e senha que você copiou do registro de contêiner do Azure. Você pode encontrá-los novamente acessando seu registro de contêiner no Azure e observando a página Configurações>Chaves de acesso.
Salve o arquivo.

Observação

Este tutorial usa as credenciais de logon do administrador do Registro de Contêiner do Azure, que são convenientes para cenários de desenvolvimento e teste. Se você está 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, confira Gerenciar o acesso ao registro de contêiner.

Defina a arquitetura de destino como AMD64

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

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

Atualizar o módulo com código personalizado

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

No gerenciador do Visual Studio Code, 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 o ambiente e a temperatura da máquina e apenas encaminha a mensagem de logon no Hub IoT se a temperatura da máquina estiver acima do 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;}
    }
}

Salve o arquivo.

Compilar sua solução do IoT Edge e efetuar push dela

Na seção anterior, você criou uma solução IoT Edge e modificou CSharpFunction para filtrar mensagens com as temperaturas relatadas do computador menores do que o limite aceitável. Agora você precisa compilar a solução como uma imagem de contêiner e enviá-la por push para seu registro de contêiner.

Abra o terminal integrado do Visual Studio Code selecionando Exibir>Terminal.
Entre 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. É possível recuperar esses valores na seção Chaves de acesso no registro do portal do Azure.
```
docker login -u <ACR username> -p <ACR password> <ACR login server>
```
Talvez você receba um aviso de segurança recomendando usar --password-stdin. Embora essa prática seja recomendada para cenários de produção, ela não serve para este tutorial. Para saber mais, confira a referência de logon do docker.
No gerenciador do Visual Studio Code, clique com o botão direito do mouse no arquivo deployment.template.json e selecione Criar e efetuar push da solução IoT Edge.

O comando de criação e de envio por push inicia três operações. Primeiro, é criada uma pasta na solução denominada config que contém o manifesto de implantação completo, criado com base nas informações do modelo de implantação e em outros arquivos da solução. Depois, ele executa docker build para montar a imagem de contêiner com base no dockerfile apropriado para sua arquitetura de destino. Por fim, ele executa docker push para enviar por push o repositório de imagens para seu registro de contêiner.

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

Exibir sua imagem de contêiner

O Visual Studio Code gera uma mensagem de êxito quando sua imagem de contêiner é enviada por push para seu registro de contêiner. Caso deseje confirmar a operação com êxito por conta própria, é possível exibir a imagem no registro.

No portal do Azure, navegue até seu registro de contêiner do Azure.
Selecione RepositóriosdeServiços>.
Você deve ver o repositório csharpfunction na lista. Escolhe este repositório para ver mais detalhes.
Na seção Marcas, você deve ver a marca 0.0.1-amd64. Essa marca indica a versão e a plataforma da imagem que você compilou. Esses valores são definidos no arquivo module.json na pasta CSharpFunction.

Implantar e executar a solução

Você pode usar o portal do Azure para implantar o módulo da Função em um dispositivo do IoT Edge, como foi feito no início rápido. Você também pode implantar e monitorar os módulos no Visual Studio Code. As seções a seguir usam o Azure IoT Edge e o Hub IoT para Visual Studio Code que estavam listados nos pré-requisitos. Instale as extensões agora, caso não o tenha feito ainda.

No gerenciador do Visual Studio Code, 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 dispositivo do IoT Edge e selecione Criar Implantação para Dispositivo Único.
Navegue até a pasta da solução que contém CSharpFunction. Abra a pasta de configuração, escolha o arquivo deployment.amd64.json e escolha Selecionar Manifesto de Implantação do Edge.
No dispositivo, expanda Módulos para ver uma lista de módulos implantados e em execução. Selecione o botão Atualizar. Você deve ver o novo CSharpFunction sendo executado junto com o módulo SimulatedTemperatureSensor e $edgeAgent e $edgeHub.

Pode demorar um pouco para que os novos módulos apareçam. Seu dispositivo IoT Edge tem de recuperar suas novas informações de implantação do IoT Hub, iniciar novos contêineres e depois retornar o status ao Hub IoT.

Exibir os dados gerados

Você pode ver todas as mensagens que chegam em seu hub IoT de todos os seus dispositivos executando Hub IoT do Azure: Iniciar o Monitoramento do Ponto de Extremidade de Evento Interno na paleta de comandos. Para interromper o monitoramento de mensagens, execute o comando Hub IoT do Azure: Parar o Monitoramento do Ponto de Extremidade de Evento Interno na paleta de comandos.

Você também pode filtrar o modo de exibição para ver todas as mensagens que chegam ao seu Hub IoT vindas de um dispositivo específico. Clique com o botão direito do mouse no dispositivo na seção Hub IoT do Azure>Dispositivos do gerenciador de Visual Studio Code e selecione Iniciar Monitoramento do Ponto de Extremidade de EventoInterno.

Limpar os recursos

Se você pretende continuar no próximo artigo recomendado, pode manter os recursos e as configurações já criados e reutilizá-los. Você também pode continuar usando o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, você pode excluir as configurações locais e os recursos do Azure criados neste artigo para evitar encargos.

Excluir recursos do Azure

A exclusão de recursos do Azure e dos grupos de recursos é irreversível. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se você criou o hub IoT em um grupo de recursos existente que contém recursos que deseja manter, exclua apenas o recurso do hub IoT, não o grupo de recursos.

Para excluir os recursos:

Entre 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.
Examine a lista de recursos que seu grupo de recursos contém. Se você deseja excluir todos eles, selecione Excluir grupo de recursos. Se quiser excluir apenas alguns, clique em cada recurso para excluí-los individualmente.

Próximas etapas

Neste tutorial, você criou um módulo de Função do Azure com o código para filtrar os dados brutos gerados pelo seu dispositivo do IoT Edge.

Siga para os próximos tutoriais para conhecer outras formas pelas quais o Azure IoT Edge pode ajudá-lo a transformar dados em informações de negócios na borda.

Localizar médias usando uma janela flutuante no Azure Stream Analytics

Compartilhar via