Compartilhar via

Tutorial: Desenvolver módulos IoT Edge usando Visual Studio Code

Aplica-se a:Marca de verificação do IoT Edge 1.5 IoT Edge 1.5

Importante

O IoT Edge 1.5 LTS é a versão com suporte. O IoT Edge 1.4 LTS chegou ao fim de sua vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este tutorial mostra como desenvolver e implantar seu código em um dispositivo do IoT Edge. Os módulos do Azure IoT Edge permitem implantar código que executa sua lógica de negócios diretamente em seu dispositivo IoT Edge. No guia de início rápido Implantar código em um dispositivo do Linux, você configura um dispositivo IoT Edge e implanta um módulo do Azure Marketplace.

Este artigo descreve as etapas para duas ferramentas de desenvolvimento do IoT Edge:

  • Interface de linha de comando (CLI) da Ferramenta de Desenvolvimento do Azure IoT Edge, preferida para desenvolvimento.
  • Extensão de ferramentas do Azure IoT Edge para o Visual Studio Code, que está no modo de manutenção.

Use o botão seletor de ferramentas no início deste artigo para escolher sua ferramenta.

Neste tutorial, você aprenderá como:

  • Configurar seu computador de desenvolvimento
  • Usar as ferramentas do IoT Edge para criar um novo projeto
  • Criar seu projeto como um contêiner do Docker e armazená-lo em um registro de contêiner do Azure
  • Implantar seu código em um dispositivo IoT Edge

O módulo do IoT Edge criado neste tutorial filtra os dados de temperatura gerados pelo dispositivo. Ele envia mensagens upstream somente se a temperatura estiver acima de um limite definido. Esse tipo de análise na borda ajuda a reduzir a quantidade de dados enviados e armazenados na nuvem.

Pré-requisitos

Um computador de desenvolvimento:

  • Use seu computador ou uma máquina virtual.
  • Verifique se o computador de desenvolvimento dá suporte à virtualização aninhada para executar um mecanismo de contêiner.
  • Você pode usar a maioria dos sistemas operacionais que executam um mecanismo de contêiner para desenvolver módulos do IoT Edge para dispositivos Linux. Este tutorial usa um computador Windows, mas também aponta diferenças conhecidas no macOS ou linux.
  • Instalar o Visual Studio Code
  • Instale a CLI do Azure.

Um dispositivo do Azure IoT Edge:

Recursos de nuvem:

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

Dica

Para obter diretrizes sobre a depuração interativa no Visual Studio Code ou no Visual Studio 2022:

Este tutorial aborda as etapas de desenvolvimento do Visual Studio Code.

Principais conceitos

Este tutorial explica como desenvolver um módulo do IoT Edge. Um módulo do IoT Edge é um contêiner com código executável. É possível implantar um ou mais módulos em um dispositivo IoT Edge. Os módulos fazem tarefas específicas, como ingerir dados de sensores, limpar e analisar dados ou enviar mensagens para um Hub IoT. Para saber mais, confira Understand Azure IoT Edge modules (Noções básicas sobre módulos do Azure IoT Edge).

Ao desenvolver módulos do IoT Edge, você deve entender a diferença entre o computador de desenvolvimento e o dispositivo IoT Edge de destino no qual o módulo é implantado. O contêiner que você cria para manter o código do módulo deve corresponder ao sistema operacional (SO) do dispositivo de destino. Por exemplo, o cenário mais comum é desenvolver um módulo em um computador Windows para direcionar um dispositivo Linux executando o IoT Edge. Nesse caso, o sistema operacional de contêiner é Linux. Ao percorrer este tutorial, lembre-se a diferença entre o sistema operacional do computador de desenvolvimento e o sistema operacional do contêiner.

Dica

Se você estiver usando o IoT Edge para Linux no Windows, o dispositivo de destino em seu cenário será a máquina virtual do Linux, não o host do Windows.

Este tutorial tem como destino dispositivos que executam o IoT Edge com contêineres Linux. Use seu sistema operacional preferencial desde que seu computador de desenvolvimento execute contêineres do Linux. O Visual Studio Code é recomendado para desenvolver com contêineres do Linux, portanto, este tutorial o usa. É possível usar o Visual Studio também, embora haja diferenças no suporte entre as duas ferramentas.

A tabela a seguir lista cenários de desenvolvimento com suporte para contêineres do Linux no Visual Studio Code e no Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Arquitetura de dispositivo do Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
Serviços do Azure Funções do Azure
Azure Stream Analytics
Azure Machine Learning
Idiomas C
C#
Java
Node.js
Python		 C
C#
Mais informações Azure IoT Edge para Visual Studio Code Ferramentas do Azure IoT Edge para Visual Studio 2019
Azure IoT Edge Tools para Visual Studio 2022

Instalar o mecanismo de contêiner

Os módulos do IoT Edge são empacotados como contêineres, portanto, você precisa de um sistema de gerenciamento de contêiner compatível com o Docker no computador de desenvolvimento para criar e gerenciá-los. O Docker Desktop é uma opção popular para desenvolvimento porque tem suporte forte a recursos. O Docker Desktop no Windows permite alternar entre contêineres do Linux e contêineres do Windows, para que você possa desenvolver módulos para diferentes tipos de dispositivos IoT Edge.

Use a documentação do Docker para instalar o Docker em seu computador de desenvolvimento:

  • Instale o Docker Desktop para Windows. Quando instala o Docker Desktop para Windows, você é solicitado se deseja usar os contêineres do Linux ou do Windows. Você pode alterar essa configuração a qualquer momento. Este tutorial usa contêineres do Linux porque os módulos têm como destino dispositivos Linux. Para saber mais, confira Switch between Windows and Linux containers (Alternar entre contêineres do Windows e do Linux).

  • Instalar o Docker Desktop para Mac

  • Leia Sobre o Docker CE para obter informações sobre a instalação em várias plataformas do Linux. Para o Subsistema do Windows para Linux (WSL), instale o Docker Desktop para Windows.

Configurar ferramentas

Instale a Ferramenta de Desenvolvimento do Azure IoT Edge baseada em Python para criar a solução do IoT Edge. Você tem duas opções:

Importante

A extensão das Ferramentas de Azure IoT Edge para Visual Studio Code está em modo de manutenção. A ferramenta de desenvolvimento recomendada é a Ferramenta de Desenvolvimento do Azure IoT Edge para linha de comando (CLI).

Use as extensões da IoT para o Visual Studio Code desenvolver módulos do IoT Edge. Essas extensões oferecem modelos de projeto, automatizam a criação do manifesto de implantação e permitem monitorar e gerenciar dispositivos do IoT Edge. Nesta seção, você instalará o Visual Studio Code e a extensão IoT; em seguida, configurará sua conta do Azure para gerenciar recursos do Hub IoT de dentro do Visual Studio Code.

  1. Instale a extensão do Azure IoT Edge.
  2. Instalar a extensão do Hub IoT do Azure.
  3. Depois de instalar as extensões, abra a paleta de comandos selecionando Exibir > Paleta de Comandos.
  4. Na paleta de comandos, pesquise e selecione o Hub IoT do Azure: Selecione o Hub IoT. Siga os prompts para selecionar sua assinatura e o Hub IoT do Azure.
  5. Abra a seção Explorador do Visual Studio Code selecionando o ícone na barra de atividades ou selecionando Exibir Explorador>.
  6. Na parte inferior da seção do Explorer, expanda o menu Hub IoT do Azure / Dispositivos recolhido. Você verá os dispositivos e dispositivos IoT Edge associados ao Hub IoT que você selecionou por meio da paleta de comandos.

Instalar ferramentas específicas da linguagem

Instale as ferramentas específicos da linguagem que você está usando para o desenvolvimento:

Criar um registro de contêiner

Neste tutorial, você usará as extensões do Azure IoT Edge e do Hub IoT do Azure para criar um módulo e criar uma imagem de contêiner a partir dos arquivos. Em seguida, você envia essa imagem por push para um registro que armazena e gerencia suas imagens. Finalmente, você implanta a imagem do seu registro para executar no dispositivo IoT Edge.

Importante

A extensão do Azure IoT Edge para o Visual Studio Code está em modo de manutenção.

Você pode usar qualquer registro compatível com o Docker para manter as imagens de contêiner. Dois serviços de registro populares do Docker são o Registro de Contêiner do Azure e o Hub do Docker. Este tutorial utiliza o Registro de Contêiner do Azure.

Caso ainda não tenha um registro de contêiner, siga estas etapas para criar um novo no Azure:

  1. No portal do Azure, selecione Criar um recurso>Contêineres>Registro de Contêiner.

  2. Forneça os seguintes valores obrigatórios para criar seu registro de contêiner:

    Campo Valor
    Subscrição Selecione uma assinatura na lista suspensa.
    Grupo de recursos Use o mesmo grupo de recursos para todos os recursos de teste criados durante os guias de início rápido e tutoriais do IoT Edge; por exemplo, IoTEdgeResources.
    Nome do registro Forneça um nome exclusivo.
    Localização Escolha um local perto de você.
    SKU Selecione Basic.

  3. Selecione Examinar + criar, depois Criar.

  4. Selecione seu novo registro de contêiner na seção Recursos da página inicial do portal do Azure para abri-lo.

  5. No painel esquerdo do registro de contêiner, selecione Chaves de acesso no menu localizado em Configurações.

    Captura de tela do local do menu Teclas de Acesso.

  6. Habilite Usuário administrador com o botão de alternância e exiba o Nome de usuário e a Senha do seu registro de contêiner.

  7. Copie os valores para Servidor de logon, Nome de usuário e Senha e salve-os em um local conveniente. É possível usar esses valores neste tutorial para fornecer acesso ao registro de contêiner.

Criar um projeto de módulo

A extensão do Azure IoT Edge oferece modelos de projeto para todas as linguagens de módulo do IoT Edge compatíveis com o Visual Studio Code. Esses modelos incluem todos os arquivos e código necessários para implantar um módulo de trabalho para testar o IoT Edge ou fornecer um ponto de partida para personalizar o modelo com sua própria lógica de negócios.

Criar um modelo de projeto

A Ferramenta de Desenvolvimento do IoT Edge simplifica o desenvolvimento do Azure IoT Edge, com comandos controlados por variáveis de ambiente. Ele ajuda você a dar os primeiros passos no desenvolvimento do IoT Edge com o contêiner de desenvolvimento do IoT Edge, juntamente com a estrutura básica da solução de IoT Edge, que inclui um módulo predefinido e todos os arquivos de configuração necessários.

  1. Crie um diretório para sua solução no caminho desejado. Altere para o diretório iotedgesolution.

    mkdir c:\dev\iotedgesolution
cd c:\dev\iotedgesolution

  2. Use o iotedgedev solution init comando para criar uma solução e configurar seu Hub IoT do Azure na linguagem de desenvolvimento de sua escolha:

    iotedgedev solution init --template csharp

O iotedgedev solution init comando solicita que você conclua várias etapas, incluindo:

  • Autenticar-se no Azure
  • Escolher uma assinatura do Azure
  • Escolher ou criar um grupo de recursos
  • Escolher ou criar um Hub IoT do Azure
  • Escolher ou criar um dispositivo Azure IoT Edge

Use o Visual Studio Code e a extensão do Azure IoT Edge. Comece criando uma solução e, em seguida, gere o primeiro módulo nessa solução. Cada solução pode incluir vários módulos.

  1. Selecione Exibir > Paleta de Comandos.
  2. Na paleta de comandos, insira e execute o comando Azure IoT Edge: New IoT Edge Solution.
  3. Navegue até a pasta na qual deseja criar a nova solução e selecione Selecionar pasta.
  4. Digite um nome para a solução.
  5. Selecione um modelo de módulo para sua linguagem de desenvolvimento preferida para ser o primeiro módulo na solução.
  6. Digite um nome para o módulo. Escolha um nome exclusivo no registro de contêiner.
  7. Insira o nome do repositório de imagem do módulo. O Visual Studio Code preenche automaticamente o nome do módulo com localhost:5000/<nome do seu módulo>. Substitua-o pelas informações de seu registro. Use localhost se você usa um registro local do Docker para testes. Se você usar o Registro de Contêiner do Azure, use o servidor de login nas configurações do registro. O servidor de entrada é semelhante ao <nome de registro>.azurecr.io. Substitua apenas a parte localhost:5000 da cadeia de caracteres, de modo que o resultado final se pareça com <nome do registro>.azurecr.io/<seu nome de módulo>.

O Visual Studio Code usa as informações fornecidas, cria uma solução do IoT Edge e, em seguida, a carrega em uma nova janela.

Depois de criar a solução, esses arquivos principais estão na solução:

  • A pasta .vscode inclui o arquivo de configuração launch.json.

  • A pasta módulos tem subpastas para cada módulo. Em cada subpasta, o arquivo module.json controla como os módulos são criados e implantados.

  • O arquivo .env lista suas variáveis de ambiente. A variável de ambiente do registro de contêiner é localhost:5000 por padrão.

  • Dois arquivos de implantação de módulo, deployment.template.json e deployment.debug.template.json, listam os módulos a serem implantados em seu dispositivo. Por padrão, a lista inclui os módulos do sistema do IoT Edge (edgeAgent e edgeHub) e módulos de exemplo, como:

    Observação

    Os módulos exatos instalados podem depender do idioma escolhido.

Definir versão de runtime do IoT Edge

A versão mais recente e estável do módulo do sistema de IoT Edge é a 1.5. Defina os módulos do sistema para a versão 1.5.

  1. No Visual Studio Code, abra o arquivo de manifesto de implantação deployment.template.json. O manifesto de implantação é um documento JSON que descreve os módulos a serem configurados nos dispositivos IoT Edge de destino.

  2. Altere a versão de runtime das imagens do módulo de runtime do sistema edgeAgent e edgeHub. Por exemplo, se você quiser usar o runtime do IoT Edge versão 1.5, altere as seguintes linhas no arquivo de manifesto de implantação:

    "systemModules": {
    "edgeAgent": {

        "image": "mcr.microsoft.com/azureiotedge-agent:1.5",

    "edgeHub": {

        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",

Forneça suas credenciais de Registro para o agente do IoT Edge

O arquivo do ambiente armazena as credenciais para o registro de contêiner e as compartilha com o runtime do IoT Edge. O runtime precisa dessas credenciais para baixar as imagens do seu contêiner para o dispositivo IoT Edge.

A extensão do IoT Edge tenta efetuar pull de suas credenciais de Registro de Contêiner do Azure e as popula no arquivo de ambiente.

Observação

O arquivo de ambiente será criado somente se você fornecer um repositório de imagens para o módulo. Se você aceitou os padrões do localhost para testar e depurar localmente, não será necessário declarar variáveis de ambiente.

Verifique se suas credenciais existem. Caso contrário, adicione-as agora:

  1. Se o Registro de Contêiner do Azure for seu registro, configure um nome de usuário e uma senha do Registro de Contêiner do Azure. Obtenha esses valores no menu Configurações>Chaves de acesso do registro de contêiner no portal do Azure.

  2. Abra o arquivo .env em sua solução de módulo.

  3. Adicione os valores nome de usuário e senha que você copiou do Registro de Contêiner do Azure. Por exemplo:

    CONTAINER_REGISTRY_SERVER="myacr.azurecr.io"
CONTAINER_REGISTRY_USERNAME="myacr"
CONTAINER_REGISTRY_PASSWORD="<registry_password>"

  4. Salve suas alterações no arquivo .env.

Observação

Este tutorial usa credenciais de administrador para o Registro de Contêiner do Azure convenientes para cenários de desenvolvimento e teste. Quando você estiver pronto para cenários de produção, recomendamos uma opção de autenticação com privilégios mínimos, como principais de serviço ou tokens limitados ao repositório. Para obter mais informações, confira Gerenciar o acesso ao registro de contêiner.

Arquitetura de destino

Selecione a arquitetura que você está direcionando para cada solução, pois isso afeta a forma como o contêiner é criado e executado. O padrão é o Linux AMD64. Para este tutorial, use uma máquina virtual do Ubuntu como o dispositivo IoT Edge e mantenha o amd64 padrão.

Se você precisar alterar a arquitetura de destino para sua solução, siga estas etapas.

  1. Abra a paleta de comandos e pesquise o Azure IoT Edge: defina a Plataforma de Destino Padrão para a Solução de Borda ou selecione o ícone de atalho na barra lateral na parte inferior da janela.
  2. Na paleta de comandos, selecione a arquitetura de destino na lista de opções.

A arquitetura de destino é definida quando você cria a imagem de contêiner em uma etapa posterior.

Atualizar o módulo com código personalizado

Cada modelo inclui um código de exemplo que usa dados simulados do sensor do módulo SimulatedTemperatureSensor e os roteia para o Hub IoT. O módulo de exemplo recebe mensagens e as transmite. A funcionalidade de pipeline mostra um conceito importante no IoT Edge: como os módulos se comunicam entre si.

Cada módulo pode ter várias filas de entrada e saída declaradas em seu código. O hub do IoT Edge em execução no dispositivo roteia mensagens da saída de um módulo para a entrada de um ou mais módulos. O código específico para declarar entradas e saídas varia entre idiomas, mas o conceito é o mesmo para todos os módulos. Para saber mais sobre o roteamento entre módulos, confira Declarar rotas.

O código C# de exemplo que vem com o modelo de projeto usa a classe ModuleClient do SDK do Hub IoT para .NET.

  1. No Explorador do Visual Studio Code, abra modules > filtermodule > ModuleBackgroundService.cs.

  2. Antes do filtermodule namespace, adicione três using instruções para tipos usados posteriormente:

    using System.Collections.Generic;     // For KeyValuePair<>
using Microsoft.Azure.Devices.Shared; // For TwinCollection
using Newtonsoft.Json;                // For JsonConvert

  3. Adicione a temperatureThreshold variável à ModuleBackgroundService classe. Essa variável define o valor que a temperatura medida deve exceder para que os dados sejam enviados para o Hub IoT.

    static int temperatureThreshold { get; set; } = 25;

  4. Adicione as classes MessageBody, Machine e Ambient. Essas classes definem o esquema esperado para o corpo de mensagens de entrada.

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

  5. Localize a função ExecuteAsync. Essa função cria e configura um ModuleClient objeto que permite que o módulo se conecte ao runtime local do Azure IoT Edge para enviar e receber mensagens. Depois de criar o ModuleClient, o código lê o valor temperatureThreshold das propriedades desejadas do módulo gêmeo. O código registra um retorno de chamada para receber mensagens de um hub do IoT Edge por meio de um ponto de extremidade chamado input1.

    Substitua a chamada para o método ProcessMessageAsync por uma nova que atualiza o nome do ponto de extremidade e o método que é chamado quando a entrada é recebida. Além disso, adicione um SetDesiredPropertyUpdateCallbackAsync método para atualizações às propriedades desejadas. Para fazer essa alteração, substitua a última linha do ExecuteAsync método pelo seguinte código:

    // Register a callback for messages that are received by the module.
// await _moduleClient.SetInputMessageHandlerAsync("input1", PipeMessage, cancellationToken);

// Read the TemperatureThreshold value from the module twin's desired properties
var moduleTwin = await _moduleClient.GetTwinAsync();
await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, _moduleClient);

// Attach a callback for updates to the module twin's desired properties.
await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);

// Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
await _moduleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, _moduleClient);

  6. Adicione o OnDesiredPropertiesUpdate método à ModuleBackgroundService classe. Esse método recebe atualizações nas propriedades desejadas do módulo gêmeo e atualiza a temperatureThreshold variável para corresponder. Todos os módulos possuem seu próprio módulo gêmeo, o que permite configurar o código em execução dentro de um módulo diretamente da nuvem.

    static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
{
    try
    {
        Console.WriteLine("Desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));

        if (desiredProperties["TemperatureThreshold"]!=null)
            temperatureThreshold = desiredProperties["TemperatureThreshold"];

    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error when receiving desired property: {0}", exception);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
    }
    return Task.CompletedTask;
}

  7. Adicione o método FilterMessages. Esse método é chamado sempre que o módulo recebe uma mensagem do hub do IoT Edge. Ele filtra as mensagens que reportam temperaturas abaixo do limite de temperatura definido através do módulo gêmeo. Ele também adiciona a MessageType propriedade à mensagem com o valor definido como Alert:

    async Task<MessageResponse> FilterMessages(Message message, object userContext)
{
    var counterValue = Interlocked.Increment(ref _counter);
    try
    {
        ModuleClient moduleClient = (ModuleClient)userContext;
        var messageBytes = message.GetBytes();
        var messageString = Encoding.UTF8.GetString(messageBytes);
        Console.WriteLine($"Received message {counterValue}: [{messageString}]");

        // Get the message body.
        var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);

        if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
        {
            Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                $"exceeds threshold {temperatureThreshold}");
            using (var filteredMessage = new Message(messageBytes))
            {
                foreach (KeyValuePair<string, string> prop in message.Properties)
                {
                    filteredMessage.Properties.Add(prop.Key, prop.Value);
                }

                filteredMessage.Properties.Add("MessageType", "Alert");
                await moduleClient.SendEventAsync("output1", filteredMessage);
            }
        }

        // Indicate that the message treatment is completed.
        return MessageResponse.Completed;
    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", exception);
        }
        // Indicate that the message treatment is not completed.
        var moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
        // Indicate that the message treatment is not completed.
        ModuleClient moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
}

  8. Salve o arquivo ModuleBackgroundService.cs.

  9. No explorador do Visual Studio Code, abra o arquivo deployment.template.json no workspace da solução IoT Edge.

  10. Como alteramos o nome do ponto de extremidade que o módulo escuta, também precisamos atualizar as rotas no manifesto de implantação para que o edgeHub envie mensagens para o novo ponto de extremidade.

    Localize a routes seção no módulo gêmeo $edgeHub . Atualize a rota sensorTofiltermodule para substituir input1 por inputFromSensor:

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"

  11. Adicione o módulo gêmeo filtermodule ao manifesto de implantação. Insira o seguinte conteúdo JSON na parte inferior da modulesContent seção, após o módulo gêmeo $edgeHub:

       "filtermodule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }

  12. Salve o arquivo deployment.template.json.

Compilar e enviar por push sua solução

Você atualizou o código do módulo e o modelo de implantação para ajudar na compreensão de alguns conceitos importantes de implantação. Agora você está pronto para criar a imagem de contêiner do módulo e efetuar push dela para seu registro de contêiner.

No Visual Studio Code, abra o arquivo de manifesto de implantação deployment.template.json. O manifesto de implantação descreve os módulos a serem configurados no dispositivo do IoT Edge de destino. Antes da implantação, você deve atualizar suas credenciais do Registro de Contêiner do Azure e suas imagens de módulo com os valores adequados createOptions . Para obter mais informações sobre os valores de createOptions, consulte Como configurar opções de criação de contêiner para módulos do IoT Edge.

Se você usar um Registro de Contêiner do Azure para armazenar a imagem do módulo, adicione suas credenciais à modulesContent > edgeAgent > settings > registryCredentials seção em deployment.template.json. Substitua pelo myacr seu próprio nome de registro e forneça sua senha e endereço do servidor de logon. Por exemplo:

"registryCredentials": {
    "myacr": {
        "username": "myacr",
        "password": "<your_acr_password>",
        "address": "myacr.azurecr.io"
    }
}

Adicione ou substitua o seguinte conteúdo stringificado ao valor createOptions para cada sistema (edgeHub e *edgeAgent) e módulo personalizado (filtermodule e tempSensor) listados. Altere os valores, se necessário:

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

Por exemplo, a filtermodule configuração deve ser semelhante a:

"filtermodule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
   "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
   "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
}

Criar imagem do Docker do módulo

Abra o terminal integrado do Visual Studio Code selecionando Terminal > Novo Terminal.

Use o comando dotnet publish para compilar a imagem de contêiner para a arquitetura Linux e amd64. Altere o diretório para o diretório filtermodule em seu projeto e execute o dotnet publish comando.

dotnet publish --os linux --arch x64 /t:PublishContainer

No momento, o modelo de ferramenta iotedgedevestá configurado para .NET 7.0. Se você quiser direcionar uma versão diferente do .NET, poderá editar o arquivo filtermodule.csproj e alterar os valores TargetFramework e PackageReference. Por exemplo, para direcionar o .NET 8.0, seu arquivo filtermodule.csproj deve parecer com isso:

<Project Sdk="Microsoft.NET.Sdk.Worker">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Devices.Client" Version="1.42.0" />
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    </ItemGroup>
</Project>

Marque a imagem do Docker com as informações, versão e arquitetura do registro de contêiner. Substitua myacr pelo seu próprio nome de registro:

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.1-amd64

Enviar por push a imagem do Docker do módulo

Forneça suas credenciais de registro de contêiner para o Docker para que ele possa efetuar push de sua imagem de contêiner para ser armazenada no registro.

  1. Entre no Docker com as credenciais do ACR (Registro de Contêiner 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 melhor 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.

  2. Entre no Registro de Contêiner do Azure. Você deve instalar a CLI do Azure para usar o az comando. Este comando solicita o seu nome de usuário e senha encontrados no registro de contêiner em Configurações > Chaves de Acesso:

    az acr login -n <ACR registry name>

    Dica

    Se você for desconectado em qualquer ponto deste tutorial, repita as etapas de entrada do Docker e do Registro de Contêiner do Azure para continuar.

  3. Envie a imagem do módulo por push para o registro local ou um registro de contêiner:

    docker push <ImageName>

    Por exemplo:

    # Push the Docker image to the local registry

docker push localhost:5000/filtermodule:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry. Replace myacr with your Azure Container Registry name.

az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Atualizar o modelo de implantação

Atualize o modelo de implantação deployment.template.json com o local da imagem do registro de contêiner. Por exemplo, se você estiver usando um Registro de Contêineres do Azure myacr.azurecr.io e sua imagem for filtermodule:0.0.1-amd64, atualize a configuração filtermodule para:

"filtermodule": {
    "version": "1.0",
    "type": "docker",
    "status": "running",
    "restartPolicy": "always",
    "settings": {
        "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
        "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
    }
}

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 é mais rápido na próxima vez que você executar os comandos.

Opcional: atualizar o módulo e a imagem

Se você fizer alterações no código do módulo, deverá recompilar e enviar por push a imagem do módulo para o registro de contêiner. Use as etapas nesta seção para atualizar a compilação e a imagem de contêiner. Você poderá ignorar esta seção se não tiver feito nenhuma alteração no código do módulo.

Abra o arquivo deployment.amd64.json na pasta de configuração recém-criada. O nome do arquivo reflete a arquitetura de destino; portanto, ele será diferente se você escolher uma arquitetura diferente.

Observe que os dois parâmetros que têm espaços reservados agora são contém seus valores adequados. A registryCredentials seção tem seu nome de usuário e senha do Registro extraídos do arquivo .env . O filtermodule possui o repositório de imagem completo com o nome, a versão e a marca de arquitetura do arquivo module.json.

  1. Abra o arquivo module.json na pasta filtermodule.

  2. Altere o número de versão da imagem de módulo. Por exemplo, incremente o número de versão de patch para "version": "0.0.2" como se você tivesse feito uma pequena correção no código do módulo.

    Dica

    As versões do módulo habilitam o controle de versão e permitem que você teste as alterações em um pequeno conjunto de dispositivos antes de implantar atualizações na produção. Se você não incrementar a versão de módulo antes de criar e efetuar push, então você substituirá o repositório em seu registro de contêiner.

  3. Salve as alterações no arquivo module.json.

Crie e efetue push da imagem atualizada com uma marca de versão 0.0.2. Por exemplo, para criar e efetuar push da imagem do registro local ou de um registro de contêiner do Azure, use os seguintes comandos:

# Build the container image for Linux and amd64 architecture.

dotnet publish --os linux --arch x64

# For local registry:
# Tag the image with version 0.0.2, x64 architecture, and the local registry.

docker tag filtermodule localhost:5000/filtermodule:0.0.2-amd64

# For Azure Container Registry:
# Tag the image with version 0.0.2, x64 architecture, and your container registry information. Replace **myacr** with your own registry name.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.2-amd64

Clique com o botão direito do mouse no arquivo deployment.template.json novamente e selecione Compilar e enviar por push a Solução IoT Edge novamente.

Abra o arquivo deployment.amd64.json novamente. Observe que o sistema de build não cria um novo arquivo ao executar o comando build e efetuar push novamente. Em vez disso, o mesmo arquivo foi atualizado para refletir as alterações. Agora a imagem filtermodule aponta para a versão 0.0.2 do contêiner.

Para verificar ainda mais o que o comando de criação e de envio por push fez, acesse o portal do Azure e navegue até o registro de contêiner. No registro de contêiner, selecione Repositórios e, sem seguida, filtermodule. Verifique se as duas versões da imagem foram enviadas por push para o registro.

Captura de tela de onde exibir as duas versões de imagem no registro de contêiner.

Solucionar problemas

Se encontrar erros ao criar e enviar sua imagem de módulo por push, isso geralmente estará relacionado à configuração do Docker em seu computador de desenvolvimento. Use as seguintes verificações para examinar sua configuração:

  • Você executou o comando docker login usando as credenciais que copiou do seu registro de contêiner? Essas credenciais são diferentes daquelas que você usa para entrar no Azure.
  • Seu repositório de contêiner está correto? Ele tem seu nome de registro de contêiner correto e seu nome de módulo correto? Abra o arquivo module.json na pasta filtermodule para verificar. O valor do repositório deve ser semelhante ao <nome> do registro.azurecr.io/filtermodule.
  • Se você usou um nome diferente de filtermodule para o seu módulo, esse nome está consistente em toda a solução?
  • Seu computador está executando o mesmo tipo de contêineres que você está criando? Este tutorial é para dispositivos IoT Edge do Linux; portanto, o Visual Studio Code deve informar amd64 ou arm32v7 na barra lateral e o Docker Desktop deve estar executando contêineres do Linux.

Implantar módulos no dispositivo

Você verificou que as imagens de contêineres criadas estão armazenadas em seu registro de contêiner; portanto, chegou a hora de implantá-las em um dispositivo. Verifique se seu dispositivo IoT Edge está em funcionamento.

Utilize o comando set-modules da CLI do IoT Edge do Azure para implantar os módulos no Hub IoT do Azure. Por exemplo, para implantar os módulos definidos no arquivo deployment.template.json no Hub IoT my-iot-hub para o dispositivo IoT Edge my-device, use o comando a seguir. Substitua os valores de cadeia de conexão hub-name, device-id e logon do Hub IoT por seus próprios valores.

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

Dica

Encontre a cadeia de conexão do Hub IoT, incluindo a chave de acesso compartilhado, no portal do Azure. Vá para o Hub IoT e selecione Configurações de segurança > Políticas de acesso compartilhado > iothubowner.

  1. No gerenciador do Visual Studio Code, na seção Hub IoT do Azure, expanda Dispositivos para ver sua lista de dispositivos IoT.

  2. Clique com o botão direito do mouse no dispositivo IoT Edge no qual você deseja implantar e selecione Criar implantação para um único dispositivo.

  3. No explorador de arquivos, navegue até a pasta config e selecione o arquivo deployment.amd64.json.

    Não use o arquivo deployment.template.json, que não tem as credenciais de registro de contêiner ou os valores de imagem de módulo nele. Se você direcionar um dispositivo Linux ARM32, o nome do manifesto de implantação será deployment.arm32v7.json.

  4. 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 os novos módulos tempSensor e filtermodule em execução em seu dispositivo.

    Pode levar alguns minutos para os módulos serem iniciados. O runtime do IoT Edge recebe seu novo manifesto de implantação, extrai as imagens de módulo do runtime do contêiner e inicia cada novo módulo.

Exibir mensagens do dispositivo

O código do módulo de exemplo obtém mensagens por meio de sua fila de entrada e as envia por meio de sua fila de saída. O manifesto de implantação configura rotas que enviam mensagens para filtermodule de tempSensor e, em seguida, encaminham mensagens de filtermodule para o Hub IoT. As extensões do Azure IoT Edge e do Hub IoT do Azure permitem que você veja as mensagens quando elas chegam ao Hub IoT do seu dispositivo.

  1. No gerenciador do Visual Studio Code, selecione o dispositivo IoT Edge que deseja monitorar e, em seguida, selecione Iniciar o Monitoramento do Ponto de Extremidade de Evento Interno.

  2. Assista à janela de saída no Visual Studio Code para ver as mensagens chegarem ao Hub IoT.

    Captura de tela da janela de saída do Visual Studio Code mostrando mensagens de entrada do dispositivo para a nuvem.

Exibir alterações no dispositivo

Para ver o que está acontecendo em seu dispositivo, use os comandos nesta seção para inspecionar o runtime do IoT Edge e os módulos em execução em seu dispositivo.

Esses comandos são para seu dispositivo IoT Edge, não para seu computador de desenvolvimento. Se estiver usando uma máquina virtual para seu dispositivo IoT Edge, conecte-se a ela agora. No Azure, acesse a página de visão geral da máquina virtual e selecione Conectar para acessar a conexão de shell segura.

  • Exiba todos os módulos implantados em seu dispositivo e verifique seu status:

    iotedge list

    Você verá quatro módulos: os dois módulos de runtime do IoT Edge, tempSensor e filtermodule. Todos os quatro devem estar listados como em execução.

  • Inspecione os logs para ver se há um módulo específico:

    iotedge logs <module name>

    Os nomes dos módulos diferenciam maiúsculas de minúsculas.

    Os logs tempSensor e filtermodule mostram as mensagens que estão processando. O módulo edgeAgent inicia os outros módulos, para que seus logs tenham informações sobre o manifesto de implantação. Se um módulo não estiver listado ou não estiver em execução, verifique se há erros nos logs do edgeAgent. O módulo edgeHub gerencia a comunicação entre os módulos e o Hub IoT. Se os módulos estiverem em execução, mas as mensagens não chegarem ao Hub IoT, verifique se há erros nos logs do edgeHub .

Limpar os recursos

Se você quiser 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, para evitar encargos, exclua a configuração local e os recursos do Azure usados neste artigo.

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 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 excluir os recursos:

  1. Entre no portal do Azure e selecione Grupos de recursos.
  2. Selecione o nome do grupo de recursos que contém os recursos de teste do 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 quiser excluir apenas alguns, clique em cada recurso para excluí-los individualmente.

Próximas etapas

Neste tutorial, você configura o Visual Studio Code em seu computador de desenvolvimento e implanta seu primeiro módulo do IoT Edge com código que filtra dados brutos gerados pelo dispositivo IoT Edge.

Continue para os próximos tutoriais para saber como o Azure IoT Edge permite implantar serviços de nuvem do Azure para processar e analisar dados na borda.

Depurar módulos do Azure IoT EdgeFunctionsStream AnalyticsServiço de Visão Personalizada

  • Last updated on