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

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Cada dispositivo IoT Edge executa pelo menos dois módulos: $edgeAgent e $edgeHub, que fazem parte do tempo de execução do IoT Edge. O dispositivo IoT Edge pode executar vários módulos para qualquer número de 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 acessar registros de contêiner privados que contêm imagens de módulo.
  • Instruções sobre como cada módulo deve ser criado e gerenciado.
• O módulo gêmeo do hub IoT Edge, que inclui como as mensagens fluem entre módulos e, eventualmente, para o Hub IoT.
• As propriedades desejadas de qualquer módulo extra twins (opcional).

Todos os dispositivos IoT Edge devem ser configurados com um manifesto de implantação. Um tempo de execução do IoT Edge recém-instalado relata um código de erro até ser configurado com um manifesto válido.

Nos tutoriais do Azure IoT Edge, você cria um manifesto de implantação passando por 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

Em um alto nível, um manifesto de implantação é uma lista de gêmeos de módulo configurados com suas propriedades desejadas. Um manifesto de implantação informa a um dispositivo IoT Edge (ou a um 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.

Dois módulos são necessários em cada manifesto de implantação: $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.

Além dos dois módulos de tempo de execução, você pode adicionar até 50 módulos próprios para serem executados em um dispositivo IoT Edge.

Um manifesto de implantação que contém apenas o tempo de execução do IoT Edge (edgeAgent e edgeHub) é válido.

Os manifestos de implantação seguem 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. Portanto, o $edgeAgent módulo gêmeo contém 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":{
              // give the IoT Edge agent access to 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 junto com o IoT Edge versão 1.0.10 e permite a ordem de inicialização do módulo. A versão 1.1 do esquema é recomendada para qualquer implantação do IoT Edge que execute 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 implantados em um dispositivo IoT Edge e como eles devem ser 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 contém a imagem do módulo, um endereço para a imagem do contêiner em um registro de contêiner e qualquer createOptions 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 deve estar em execução ou interrompido quando implantado pela primeira vez. Obrigatório.

• RestartPolicy: Quando e se o agente do IoT Edge deve reiniciar o módulo se ele parar. Se o módulo for interrompido 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. Em que ordem o agente do IoT Edge deve iniciar os módulos quando implantado pela primeira vez. A ordem é declarada com números inteiros, onde um módulo dado um valor de inicialização de 0 é iniciado 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 começar antes de ir para o próximo.

  A ordem de inicialização é útil se alguns módulos dependerem de outros. Por exemplo, você pode querer que o módulo edgeHub comece primeiro para que esteja pronto para rotear mensagens quando os outros módulos forem iniciados. Ou você pode querer iniciar um módulo de armazenamento antes de iniciar módulos que enviam dados para ele. No entanto, você deve sempre projetar seus módulos para lidar com falhas de outros módulos. É da natureza dos contentores que possam parar e reiniciar a qualquer momento e a qualquer número de vezes.

  Nota

  As alterações nas propriedades de um módulo resultarão na reinicialização desse módulo. Por exemplo, uma reinicialização acontecerá se você alterar 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, o módulo não será reiniciado.

Declarar rotas

O hub IoT Edge gerencia a comunicação entre módulos, Hub IoT e quaisquer dispositivos downstream. Portanto, o $edgeHub módulo gêmeo contém uma propriedade desejada chamada rotas que declara como as mensagens são passadas dentro de uma implantação. Você pode ter várias rotas dentro da mesma implantação.

As rotas são declaradas nas propriedades $edgeHub desejadas com a seguinte 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 junto com o IoT Edge versão 1.0.10 e permite priorização de rota e tempo de vida. A versão 1.1 do esquema é recomendada para qualquer implantação do IoT Edge que execute a versão 1.0.10 ou posterior.

Cada rota precisa de uma fonte de onde as mensagens vêm e um coletor para onde as mensagens vão. A condição é uma peça opcional que você pode usar para filtrar mensagens.

Você pode atribuir prioridade às rotas que deseja garantir que processem suas mensagens primeiro. Esse recurso é útil em cenários em que a conexão upstream é fraca ou limitada e você tem dados críticos que devem ser priorizados em relação às 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 IoT, os módulos podem declarar 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 são úteis para gerenciar várias rotas. Os dispositivos downstream podem usar a classe DeviceClient dos SDKs IoT para enviar mensagens para dispositivos de gateway IoT Edge da mesma forma que enviariam mensagens para o Hub IoT. Para obter mais informações, consulte Compreender e usar SDKs do Hub IoT do Azure.

A propriedade source pode ser qualquer um dos seguintes valores:

Condição

A condição é opcional em uma declaração de rota. Se você quiser passar todas as mensagens da fonte para o coletor, basta deixar de fora a cláusula WHERE completamente. Ou você pode usar a linguagem de consulta do Hub IoT para filtrar determinadas mensagens ou tipos de mensagem que satisfaçam a 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 passam entre módulos no IoT Edge são formatadas da mesma forma que as mensagens que passam entre seus dispositivos e o Hub IoT do Azure. Todas as mensagens são formatadas como JSON e têm parâmetros systemProperties, appProperties e body .

Você pode criar consultas em torno de qualquer um dos três parâmetros com a seguinte sintaxe:

• Propriedades do sistema: $<propertyName> ou {$<propertyName>}
• Propriedades da aplicação: <propertyName>
• Propriedades do corpo: $body.<propertyName>

Para obter exemplos sobre como criar consultas para propriedades de mensagens, consulte Expressões de consulta de rotas de mensagens do dispositivo para a nuvem.

Um exemplo específico do IoT Edge é quando você deseja filtrar mensagens que chegaram a um dispositivo de gateway a partir de um dispositivo downstream. As mensagens enviadas de módulos incluem uma propriedade do sistema chamada connectionModuleId. Portanto, se você quiser rotear mensagens de dispositivos downstream diretamente para o Hub IoT, use a seguinte rota para excluir mensagens do módulo:

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

Sink

O coletor define para onde as mensagens são enviadas. Apenas módulos e Hub IoT podem receber mensagens. As mensagens não podem ser encaminhadas para outros dispositivos. Não há opções de curinga na propriedade da pia.

A propriedade do coletor pode ser qualquer um dos seguintes valores:

O IoT Edge fornece pelo menos uma vez garantias. O hub IoT Edge armazena mensagens localmente caso uma rota não possa entregar a mensagem ao coletor. 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 as mensagens até o tempo especificado na storeAndForwardConfiguration.timeToLiveSecs propriedade das propriedades desejadas do hub IoT Edge.

Prioridade e tempo de vida

As rotas podem ser declaradas com apenas uma cadeia de caracteres definindo a rota ou como um objeto que usa 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 podem ser de 0 a 9, inclusive, onde 0 é a prioridade mais alta. As mensagens são enfileiradas com base em seus pontos de extremidade. Todas as mensagens de prioridade 0 direcionadas a um ponto de extremidade específico são processadas antes que qualquer mensagem de prioridade 1 direcionada ao mesmo ponto de extremidade seja processada e mais adiante. Se várias rotas para o mesmo ponto de extremidade tiverem a mesma prioridade, suas mensagens serão processadas por ordem de chegada. Se nenhuma prioridade for especificada, a rota será atribuída à prioridade mais baixa.

A propriedade timeToLiveSecs herda seu valor de storeAndForwardConfiguration do hub IoT Edge, a menos que explicitamente definida. O valor pode ser qualquer número inteiro positivo.

Para obter informações detalhadas sobre como as filas de prioridade são gerenciadas, consulte a página de referência para Prioridade de rota e tempo de vida.

Definir ou atualizar as propriedades desejadas

O manifesto de implantação especifica 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 especificar as propriedades desejadas de um gêmeo de módulo no manifesto de implantação, o Hub IoT não modificará o gêmeo de módulo de forma alguma. Em vez disso, você pode definir as propriedades desejadas programaticamente.

Os mesmos mecanismos que permitem modificar gêmeos de dispositivo são usados para modificar 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

• Para obter uma lista completa das propriedades que podem ou devem ser incluídas no $edgeAgent e no $edgeHub, consulte Propriedades do agente do IoT Edge e do hub do IoT Edge.

• Agora que você já sabe como os módulos do IoT Edge são usados, entenda os requisitos e as ferramentas para o desenvolvimento dos módulos do IoT Edge.