Partilhar via

Saiba como implementar módulos e estabelecer rotas no IoT Edge

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 suportada. O IoT Edge 1.4 LTS está em fim de vida útil a partir de 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

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

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

  • O módulo gêmeo do agente IoT Edge, que inclui três componentes:
    • A imagem do contêiner para cada módulo executado no dispositivo
    • As credenciais para usar registros de contêiner privados com imagens de módulo
    • Instruções sobre como cada módulo é criado e gerenciado
  • O módulo gémeo do IoT Edge hub, que inclui como as mensagens fluem entre os módulos e para o IoT Hub.
  • As propriedades desejadas de quaisquer módulos extras de gémeos (opcionais)

Todos os dispositivos IoT Edge precisam de um manifesto de implantação. Um runtime do IoT Edge recém-instalado mostra um código de erro até estar configurado com um manifesto que seja 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 REST ou o SDK do Serviço de Hub IoT. Para obter mais informações, consulte Compreender as implantações do IoT Edge.

Criar um manifesto de implementação

Um manifesto de implantação é uma lista de gêmeos de módulo definidos com suas propriedades desejadas. Ele informa a um dispositivo IoT Edge ou grupo de dispositivos quais módulos instalar e como configurá-los. Os manifestos de implantação incluem as propriedades desejadas para cada gêmeo de módulo. Os dispositivos 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 fazem parte do tempo de execução 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 Compreender o tempo de execução do 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 tempo de execução.

Um manifesto de implantação que tenha apenas o tempo de execução 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

Defina como o tempo de execução do IoT Edge instala os módulos em sua implantação. O agente IoT Edge é o componente de tempo de execução que gerencia a instalação, as atualizações e os relatórios de status de um dispositivo IoT Edge. Assim, o $edgeAgent módulo twin tem as informações de configuração e gerenciamento para todos os módulos. Essas informações incluem os parâmetros de configuração para o próprio agente do IoT Edge.

As propriedades $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 gestão de módulos

A lista de propriedades desejadas do agente 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 devem ser incluídas, consulte 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 settings que inclui a imagem do módulo, o endereço da imagem no registo de contentores e quaisquer opções de criação para configurar a imagem na inicialização. Para obter mais informações, consulte Como configurar opções de criação de contêiner para módulos do IoT Edge.

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

  • Status: Se o módulo é executado ou parado quando implantado pela primeira vez. Obrigatório.

  • RestartPolicy: Quando e se o agente do IoT Edge reinicia o módulo caso ele pare. Se o módulo parar sem erros, ele não será iniciado automaticamente. Para obter mais informações, consulte Docker Docs - Iniciar contêineres automaticamente. Obrigatório.

  • 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 números inteiros, onde 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 sempre começa primeiro. Opcional.

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

    A ordem de inicialização ajuda se alguns módulos dependerem de outros. Por exemplo, talvez você queira que o módulo edgeHub comece primeiro para que 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 a qualquer número de vezes.

    Nota

    A alteração das propriedades de um módulo reinicia esse módulo. Por exemplo, uma reiniciação ocorre se se alterarem as propriedades para:

    • imagem do módulo
    • Opções de criação do Docker
    • variáveis de ambiente
    • Política de reinicialização
    • Política de extração de imagem
    • versão
    • ordem de inicialização

    Se nenhuma propriedade do módulo for alterada, uma reinicialização do módulo não será acionada.

Declarar rotas

O hub IoT Edge gerencia a comunicação entre módulos, Hub IoT e dispositivos downstream. O $edgeHub módulo gêmeo 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 do hub IoT Edge versão 1 foi lançado com o IoT Edge versão 1.0.10 e permite definir a priorização de rota e o tempo de vida. 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 fonte para mensagens recebidas e um coletor para mensagens enviadas. 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 vez de mensagens de telemetria padrão.

Origem

A fonte especifica de onde vêm as mensagens. O IoT Edge pode rotear 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 da 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 Compreender e usar SDKs do Hub IoT do Azure.

A propriedade source pode usar qualquer um destes valores:

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

Condição

A condição é opcional em uma declaração de rota. Para passar todas as mensagens da fonte 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 suportam a filtragem de mensagens com base em tags ou propriedades gêmeas.

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 parâmetros systemProperties, appProperties e body .

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

  • Propriedades do sistema: $<propertyName> ou {$<propertyName>}
  • Propriedades da aplicação: <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 mensagem de dispositivo para nuvem.

Por exemplo, talvez você queira filtrar mensagens que chegam a um dispositivo de gateway a partir de um dispositivo downstream. As mensagens enviadas de 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

Lavatório

O coletor define para onde as mensagens são enviadas. Apenas módulos e Hub IoT podem receber mensagens. Não é possível encaminhar mensagens para outros dispositivos. A propriedade de destino não suporta caracteres universais.

A propriedade sink pode usar qualquer um destes valores:

Lavatório 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 pelo menos uma vez. O hub IoT Edge armazena mensagens localmente caso uma rota não consiga entregar a mensagem ao destino. Por exemplo, se o hub IoT Edge não puder se conectar ao Hub IoT ou se o módulo de destino não estiver conectado.

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

Prioridade e tempo de vida

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 tempo de vida.

Opção 1

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

Opção 2 (introduzida no IoT Edge versão 1.0.10 com esquema de hub 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, onde 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 chegarem. Se você não definir uma prioridade, a rota usará a prioridade mais baixa.

A propriedade timeToLiveSecs usa o valor de 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 tempo de vida.

Definir ou atualizar as propriedades desejadas

O manifesto de implantação define as propriedades desejadas para cada módulo implantado no dispositivo IoT Edge. As propriedades desejadas no manifesto de implantação substituem todas as propriedades desejadas atualmente no módulo gêmeo.

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

Os mesmos mecanismos que permitem que você mude gêmeos de dispositivo também permitem que você mude gêmeos de módulo. 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óximos passos