Tutorial: Implantar Azure Functions como módulos de IoT Edge

Aplica-se a: IoT Edge 1.5

Use Azure Functions para implantar o código que executa sua lógica de negócios diretamente em seus dispositivos Azure IoT Edge. Este tutorial mostra como criar e implantar uma função Azure que filtra os dados do sensor em um dispositivo de IoT Edge simulado. Use o dispositivo de IoT Edge simulado que você criou nos inícios rápidos. Neste tutorial, você aprenderá como:

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

Se você não tiver uma conta Azure, crie uma conta free antes de começar.

Pré-requisitos

Antes de iniciar este tutorial, siga o tutorial para configurar seu ambiente de desenvolvimento para o desenvolvimento de contêiner do Linux: Develop Azure IoT Edge módulos usando Visual Studio Code. Ao concluir, você tem os seguintes pré-requisitos disponíveis:

• Uma camada gratuita ou padrão IoT Hub em Azure.
• Um dispositivo AMD64 executando Azure IoT Edge com contêineres do Linux. Use o início rápido para configurar um dispositivo Linux ou Windows dispositivo.
• Um registro de contêiner, como Azure Container Registry.
• Visual Studio Code configurado com as extensões Azure IoT Edge e Azure IoT Hub. As ferramentas da extensão Azure IoT Edge para o Visual Studio Code estão no modo de manutenção.
• Baixe e instale um sistema de gerenciamento de contêiner compatível com o Docker em seu computador de desenvolvimento. Defina-o para executar contêineres do Linux.

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

• C# para Visual Studio Code (alimentado pela extensão OmniSharp)
• O SDK do .NET Core

Criar um projeto de função

Azure IoT Edge para Visual Studio Code fornece recursos de gerenciamento e modelos de código. Nesta seção, você usará Visual Studio Code para criar uma solução IoT Edge com uma função Azure.

Criar um novo projeto

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

1. Abra Visual Studio Code no computador de desenvolvimento.

2. Abra a paleta de comandos Visual Studio Code selecionando View > Command Palette.

3. Na paleta de comandos, adicione e execute o comando Azure IoT Edge: Nova solução de 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 Visual Studio Code criar os arquivos da 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 o módulo CSharpFunction.
   • Forneça um repositório de imagem do Docker para o módulo: um repositório de imagens inclui o nome do registro de contêiner e o nome da imagem do contêiner. O portal preenche previamente a sua imagem de contêiner da última etapa. Substitua localhost:5000 pelo valor Login server do registro de contêiner Azure. Você pode recuperar o servidor Login da página Overview do registro de contêiner no portal Azure. A cadeia de caracteres final se parece com <registry name>.azurecr.io/csharpfunction.

   

Adicionar suas credenciais de registro

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

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

1. No Visual Studio Code Explorer, abra o arquivo .env.
2. Atualize os campos com os valores username e password copiados do registro de contêiner Azure. Para encontrá-los novamente, acesse o registro de contêiner no Azure e verifique a página Settings > Access keys.
3. Salve o arquivo.

Defina a arquitetura de destino como AMD64

Os módulos do Azure Functions no IoT Edge são suportados apenas em contêineres baseados em Linux AMD64. A arquitetura de destino padrão para Visual Studio Code é o Linux AMD64, mas você pode defini-la explicitamente como Linux AMD64 aqui.

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

Atualizar o módulo com código personalizado

Adicione código para que o módulo CSharpFunction processe mensagens na borda antes de encaminhá-las para IoT Hub.

1. No Visual Studio Code Explorer, abra modules > CSharpFunction > CSharpFunction.cs.

2. Substitua o conteúdo do arquivo CSharpFunction.cs pelo código a seguir. Esse código recebe telemetria sobre temperatura ambiente e computador e encaminha a mensagem para IoT Hub somente se a temperatura do computador 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;}
       }
   }
   

3. Salve o arquivo.

Criar e publicar sua solução de IoT Edge

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

1. Abra o terminal integrado Visual Studio Code. Selecione Visualizar > Terminal.

2. Faça login no Docker pelo terminal. Use o nome de usuário, a senha e o servidor de autenticação do registro de contêiner Azure. Obtenha esses valores da seção Access keys do registro no 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.

3. No Visual Studio Code Explorer, clique com o botão direito do mouse no arquivo deployment.template.json e selecione Build e Push IoT Edge Solution.

   O comando de criação e de envio por push inicia três operações. Primeiro, ele cria uma nova pasta na solução chamada configuração que tem o manifesto de implantação completo, que é criado a partir do modelo de implantação e de outros arquivos de solução. Em segundo lugar, ele executa docker build para criar a imagem de contêiner com base no Dockerfile correto 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 é mais rápido na próxima vez que você executar os comandos.

Exibir sua imagem de contêiner

Visual Studio Code mostra uma mensagem de êxito quando você envia sua imagem de contêiner para o registro de contêiner. Para confirmar a operação, visualize a imagem no registro.

1. No portal do Azure, vá para o registro de contêiner do Azure.
2. Selecione Repositórios de Serviços>.
3. Você verá o repositório csharpfunction na lista. Selecione este repositório para exibir mais detalhes.
4. Na seção Marcas , você verá a marca 0.0.1-amd64 . Esta tag mostra a versão e a plataforma da imagem que você criou. O arquivo module.json na pasta CSharpFunction define esses valores.

Implantar e executar a solução

Use o portal do Azure para implantar seu módulo Function em um dispositivo IoT Edge como no guia de início rápido. Você também pode implantar e monitorar módulos de Visual Studio Code. As seções a seguir usam o Azure IoT Edge e IoT Hub para extensões de Visual Studio Code listadas nos pré-requisitos. Instale as extensões agora, se ainda não tiver feito isso.

1. No Visual Studio Code Explorer, na seção Azure IoT Hub , expanda Devices para ver a lista de dispositivos IoT.

2. Clique com o botão direito do mouse no nome do dispositivo IoT Edge e selecione Create Deployment for Single Device.

3. Vá para a pasta de solução que tem o CSharpFunction. Abra a pasta de configuração, escolha o arquivo deployment.amd64.json e escolha Selecionar Manifesto de Implantação do Edge.

4. No dispositivo, expanda Módulos para ver uma lista de módulos implantados e em execução. Selecione o botão Atualizar. Você pode ver o novo CSharpFunction em execução junto com o módulo SimulatedTemperatureSensor , $edgeAgent e $edgeHub.

   Pode levar alguns instantes para que os novos módulos apareçam. O dispositivo IoT Edge recupera suas novas informações de implantação de IoT Hub, inicia os novos contêineres e relata o status de volta para IoT Hub.

   

Exibir os dados gerados

Veja todas as mensagens que chegam ao hub IoT de seus dispositivos executando Azure IoT Hub: Iniciar o Monitoramento do Ponto de Extremidade de Evento Interno na Paleta de Comandos. Para interromper o monitoramento de mensagens, execute Azure IoT Hub: Parar de Monitorar Ponto de Extremidade de Evento Integrado no Command Palette.

Para filtrar a exibição e ver mensagens de um dispositivo específico, clique com o botão direito do mouse no dispositivo na seção Azure IoT Hub > Devices do gerenciador de Visual Studio Code e selecione Start Monitoring Built-in Event Endpoint.

Limpar os recursos

Se você planeja continuar para o próximo artigo recomendado, mantenha os recursos e configurações criados e reutilize-os. Você também pode continuar usando o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, exclua a configuração local e os recursos Azure que você criou neste artigo para evitar encargos.

Excluir recursos de Azure

Não é possível desfazer a exclusão dos recursos do Azure e grupos de recursos. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se você criou o IoT Hub dentro de um grupo de recursos existente que tem recursos que deseja manter, exclua apenas o recurso IoT Hub em si, não o grupo de recursos.

Para excluir os recursos:

1. Entre no Azure portal e selecione Resource groups.
2. Selecione o nome do grupo de recursos que contém seus recursos de teste IoT Edge.
3. Examine a lista de recursos que seu grupo de recursos contém. Se você deseja excluir todos eles, selecione Excluir grupo de recursos. Se você quiser excluir apenas alguns deles, selecione cada recurso para excluí-los individualmente.

Próximas etapas

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

Continue para os próximos tutoriais para aprender outras maneiras pelas quais o Azure IoT Edge pode ajudá-lo a transformar dados em insights de negócios na edge.