Aprenda a implantar módulos e estabelecer rotas no IoT Edge

2025-05-20

Aplica-se a: IoT Edge 1.5

Importante

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

Cada dispositivo IoT Edge executa ao menos dois módulos: $edgeAgent e $edgeHub, que fazem parte do runtime do IoT Edge. Um dispositivo IoT Edge pode executar vários módulos para processos diferentes. Use um manifesto de implantação para informar ao dispositivo quais módulos instalar e como configurá-los para trabalhar em conjunto.

O manifesto de implantação é um documento JSON que descreve:

O módulo gêmeo do agente do IoT Edge, que inclui três componentes:
- A imagem de contêiner para cada módulo executado no dispositivo
- As credenciais para acessar os registros de contêiner privado que contêm as imagens de módulo
- Instruções sobre como cada módulo é criado e gerenciado
O módulo gêmeo do hub do IoT Edge, que inclui como as mensagens fluem entre módulos e o Hub IoT
As propriedades desejadas de qualquer módulo adicional gêmeo (opcional)

Todos os dispositivos do IoT Edge precisam de um manifesto de implantação. Um runtime do IoT Edge recém-instalado mostra um código de erro até que ele seja configurado com um manifesto válido.

Nos tutoriais do Azure IoT Edge, você cria um manifesto de implantação usando um assistente no portal do Azure IoT Edge. Você também pode aplicar um manifesto de implantação programaticamente usando o REST ou o SDK do Serviço do Hub IoT. Para saber mais, veja Noções básicas sobre implantações do IoT Edge.

Criar um manifesto de implantação

Um manifesto de implantação é uma lista de módulos gêmeos definidos com suas propriedades desejadas. Ele informa a um dispositivo ou grupo de dispositivos do IoT Edge quais módulos instalar e como configurá-los. Manifestos de implantação incluem as propriedades desejadas para cada módulo gêmeo. Os dispositivos do IoT Edge relatam as propriedades relatadas para cada módulo.

Cada manifesto de implantação requer dois módulos: $edgeAgent e $edgeHub. Esses módulos são parte do runtime do IoT Edge que gerencia o dispositivo IoT Edge e os módulos em execução nele. Para obter mais informações sobre esses módulos, consulte Entender o runtime do Azure IoT Edge e sua arquitetura.

Você pode adicionar até 50 módulos adicionais para serem executados em um dispositivo IoT Edge, além dos dois módulos de runtime.

Um manifesto de implantação que tem apenas o runtime do IoT Edge ($edgeAgent e $edgeHub) é válido.

Os manifestos de implantação usam esta estrutura:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configurar módulos

Definir como o runtime do IoT Edge instala os módulos na sua implantação. O agente do IoT Edge é o componente de runtime que gerencia a instalação, atualizações e relatório de status para um dispositivo IoT Edge. Portanto, o módulo gêmeo $edgeAgent tem as informações de configuração e gerenciamento para todos os módulos. Essas informações incluem os parâmetros de configuração do próprio agente do IoT Edge.

As propriedades de $edgeAgent seguem esta estrutura:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

O esquema do agente do IoT Edge versão 1.1 foi lançado com o IoT Edge versão 1.0.10 e permite definir a ordem de inicialização do módulo. Use o esquema versão 1.1 para qualquer implantação do IoT Edge executando a versão 1.0.10 ou posterior.

Configuração e gerenciamento do módulo

A lista de propriedades desejadas do agente do IoT Edge é onde você define quais módulos são executados em um dispositivo IoT Edge e como eles são configurados e gerenciados.

Para obter uma lista completa das propriedades desejadas que podem ou precisam ser incluídas, confira Propriedades do agente do IoT Edge e do hub do IoT Edge.

Por exemplo:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Cada módulo tem uma propriedade de configurações com a imagem do módulo, um endereço para a imagem de contêiner em um registro de contêiner e qualquer createOptions para configurar a imagem na inicialização. Para obter mais informações, confira Como configurar opções de criação de contêiner para módulos de IoT Edge.

O módulo edgeHub e os módulos personalizados também têm três propriedades que dizem ao agente do IoT Edge como gerenciá-los:

Status: se o módulo é executado ou interrompido quando implantado pela primeira vez. Obrigatória.
RestartPolicy: Quando e se o agente do IoT Edge reinicia o módulo caso ele pare. Se o módulo for interrompido sem erros, ele não será iniciado automaticamente. Para obter mais informações, consulte Documentos do Docker – Iniciar contêineres automaticamente. Obrigatória.
StartupOrder: introduzido no IoT Edge versão 1.0.10. A ordem que o agente do IoT Edge usa para iniciar os módulos quando implantado pela primeira vez. A ordem usa inteiros, em que um módulo com um valor de inicialização de 0 começa primeiro e, em seguida, números mais altos seguem. O módulo edgeAgent não tem um valor de inicialização porque ele sempre é iniciado primeiro. Opcional.

O agente do IoT Edge inicia os módulos na ordem do valor de inicialização, mas não aguarda que cada módulo seja concluído antes de iniciar o próximo.

A ordem de inicialização ajuda se alguns módulos dependem de outros. Por exemplo, talvez você queira que o módulo edgeHub seja iniciado primeiro para que ele esteja pronto para rotear mensagens quando os outros módulos forem iniciados. Ou talvez você queira iniciar um módulo de armazenamento antes de iniciar módulos que enviam dados para ele. Mas sempre projete seus módulos para lidar com falhas de outros módulos. Os contêineres podem parar e reiniciar a qualquer momento e em qualquer número de vezes.
Observação

Alterar as propriedades de um módulo reinicia esse módulo. Por exemplo, uma reinicialização ocorrerá se você alterar as propriedades para:
- imagem do módulo
- Opções de criação de docker
- variáveis de ambiente
- política de reinicialização
- política de pull de imagem
- versão
- ordem de Inicialização
Se nenhuma propriedade de módulo for alterada, uma reinicialização de módulo não será disparada.

Declarar rotas

O hub do IoT Edge gerencia a comunicação entre módulos, Hub IoT e dispositivos downstream. O módulo gêmeo $edgeHub tem uma propriedade desejada chamada rotas que define como as mensagens se movem dentro de uma implantação. Você pode configurar várias rotas na mesma implantação.

Declare rotas nas propriedades desejadas do $edgeHub usando esta sintaxe:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

O esquema de hub do IoT Edge versão 1 foi lançado com o IoT Edge versão 1.0.10 e permite definir a priorização da rota e o tempo de vida útil. Use o esquema versão 1.1 para qualquer implantação do IoT Edge executando a versão 1.0.10 ou posterior.

Cada rota precisa de uma origem para mensagens de entrada e um coletor para mensagens de saída. A condição é opcional e permite filtrar mensagens.

Atribua prioridade às rotas para processar mensagens importantes primeiro. Esse recurso ajuda quando a conexão upstream é fraca ou limitada e você precisa priorizar dados críticos em relação às mensagens de telemetria padrão.

Origem

A origem especifica de onde as mensagens são provenientes. O IoT Edge pode rotear as mensagens de módulos ou dispositivos downstream.

Com os SDKs de IoT, os módulos podem definir filas de saída específicas para suas mensagens usando a classe ModuleClient. As filas de saída não são necessárias, mas ajudam a gerenciar várias rotas. Os dispositivos downstream usam a classe DeviceClient nos SDKs de IoT para enviar mensagens para dispositivos de gateway do IoT Edge, assim como enviam mensagens para o Hub IoT. Para obter mais informações, consulte Noções básicas e uso de SDKs do Hub IoT do Azure.

A propriedade de origem pode usar qualquer um desses valores:

Origem	Descrição
`/*`	Todas as mensagens do dispositivo para a nuvem ou notificações de alteração de gêmeo de qualquer módulo ou dispositivo downstream
`/twinChangeNotifications`	Qualquer alteração de gêmeo (propriedades relatadas) proveniente de qualquer dispositivo de módulo ou downstream
`/messages/*`	Qualquer mensagem de dispositivo para nuvem enviada por um módulo por meio de alguma ou nenhuma saída ou por um dispositivo downstream
`/messages/modules/*`	Qualquer mensagem de dispositivo para nuvem enviada por um módulo por meio de algumas ou nenhuma saída
`/messages/modules/<moduleId>/*`	Qualquer mensagem de dispositivo para nuvem enviada por um módulo específico por meio de algumas ou nenhuma saída
`/messages/modules/<moduleId>/outputs/*`	Qualquer mensagem de dispositivo para nuvem enviada por um módulo específico por meio de alguma saída
`/messages/modules/<moduleId>/outputs/<output>`	Qualquer mensagem de dispositivo para nuvem enviada por um módulo específico por meio de uma saída específica

Condição

A condição é opcional em uma declaração de rota. Para passar todas as mensagens da origem para o coletor, deixe de fora a cláusula WHERE . Ou use a linguagem de consulta do Hub IoT para filtrar mensagens ou tipos de mensagem que atendam à condição. As rotas do IoT Edge não dão suporte a mensagens de filtragem com base em propriedades ou marcas do gêmeo.

As mensagens que se movem entre módulos no IoT Edge usam o mesmo formato que as mensagens entre seus dispositivos e o Hub IoT do Azure. Todas as mensagens usam o formato JSON e têm systemProperties, appProperties e parâmetros de corpo .

Crie consultas em torno de qualquer um dos três parâmetros usando essa sintaxe:

Propriedades do sistema: $<propertyName> ou {$<propertyName>}
Propriedades do aplicativo: <propertyName>
Propriedades do corpo: $body.<propertyName>

Para obter exemplos de como criar consultas para propriedades de mensagem, consulte expressões de consulta de rotas de mensagens de dispositivo para nuvem.

Por exemplo, talvez você queira filtrar mensagens que chegam a um dispositivo de gateway de um dispositivo downstream. As mensagens enviadas dos módulos incluem uma propriedade do sistema chamada connectionModuleId. Para rotear mensagens de dispositivos downstream diretamente para o Hub IoT e excluir mensagens de módulo, use esta rota:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Coletor

O coletor define para onde as mensagens são enviadas. Somente os módulos e o Hub IoT podem receber mensagens. Você não pode rotear mensagens para outros dispositivos. A propriedade do coletor não dá suporte a curingas.

A propriedade do coletor pode usar qualquer um desses valores:

Coletor	Descrição
`$upstream`	Enviar a mensagem para o Hub IoT
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Enviar a mensagem para uma entrada específica de um módulo específico

O IoT Edge fornece garantias at-least-once. O hub do Edge armazena mensagens localmente se uma rota não conseguir entregar a mensagem para seu coletor. Por exemplo, se o hub do IoT Edge não puder se conectar ao Hub IoT ou o módulo de destino não estiver conectado.

O hub do IoT Edge armazena mensagens até o tempo definido na storeAndForwardConfiguration.timeToLiveSecs propriedade das propriedades desejadas do hub IoT Edge.

Prioridade e vida útil

Declare rotas como uma cadeia de caracteres que define a rota ou como um objeto com uma cadeia de caracteres de rota, um inteiro de prioridade e um inteiro de vida útil.

Opção 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Opção 2 (introduzida no IoT Edge versão 1.0.10 com o esquema do hub do IoT Edge versão 1.1)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Os valores de prioridade variam de 0 a 9, em que 0 é a prioridade mais alta. As mensagens são enfileiradas por seus pontos de extremidade. Todas as mensagens de prioridade 0 para um ponto de extremidade específico são processadas antes de qualquer mensagem de prioridade 1 para o mesmo ponto de extremidade. Se várias rotas para o mesmo ponto de extremidade tiverem a mesma prioridade, as mensagens serão processadas na ordem em que chegam. Se você não definir uma prioridade, a rota usará a prioridade mais baixa.

A propriedade timeToLiveSecs usa o valor da storeAndForwardConfiguration do hub IoT Edge, a menos que você o defina diretamente. O valor pode ser qualquer número inteiro positivo.

Para obter detalhes sobre como as filas de prioridade são gerenciadas, consulte Prioridade de rota e vida útil.

Definir ou atualizar as propriedades desejadas

O manifesto de implantação define as propriedades desejadas para cada módulo implantado no dispositivo do IoT Edge. Quando as propriedades no manifesto de implantação substituem qualquer propriedade desejada atualmente no gêmeo do módulo.

Se você não definir as propriedades desejadas de um módulo gêmeo no manifesto de implantação, o Hub IoT não alterará o módulo gêmeo. Em vez disso, defina as propriedades desejadas programaticamente.

Os mesmos mecanismos que permitem alterar dispositivos gêmeos também permitem que você altere os módulos gêmeos. Para obter mais informações, consulte o guia do desenvolvedor do módulo gêmeo.

Exemplo de manifesto de implantação

O exemplo a seguir mostra a aparência de um documento de manifesto de implantação válido.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Próximas etapas

Para obter uma lista completa das propriedades que você pode ou deve incluir em $edgeAgent e $edgeHub, consulte Propriedades do agente do IoT Edge e do hub do IoT Edge.
Agora que você sabe como os módulos do IoT Edge funcionam, saiba mais sobre os requisitos e as ferramentas para desenvolver módulos do IoT Edge.