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

Aplica-se a: IoT Edge 1.5

Cada dispositivo IoT Edge executa pelo menos dois módulos: $edgeAgent e $edgeHub, que fazem parte do tempo de execução IoT Edge. Um dispositivo IoT Edge pode executar múltiplos 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 gémeo do módulo IoT Edge agent, que inclui três componentes:
  • A imagem do contentor para cada módulo que corre no dispositivo.
  • As credenciais para usar registos privados de contentores com imagens de módulos.
  • Instruções sobre como cada módulo é criado e gerido.
• O módulo gémeo IoT Edge hub, que descreve como as mensagens fluem entre módulos e para o IoT Hub.
• As propriedades desejadas de qualquer módulo gémeo extra (opcional).

Todos os dispositivos IoT Edge precisam de um manifesto de implementação. Um runtime IoT Edge recém-instalado mostra um código de erro até configurar um manifesto válido.

Nos tutoriais do Azure IoT Edge, constrói um manifesto de implementação usando um assistente no portal Azure IoT Edge. Também pode aplicar um manifesto de implementação programaticamente usando REST ou o IoT Hub Service SDK. Para mais informações, consulte Compreender implementações de 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. Indica a um dispositivo IoT Edge ou grupo de dispositivos quais os módulos a instalar e como os configurar. Os manifestos de implantação incluem as propriedades desejadas para cada gêmeo de módulo. Dispositivos IoT Edge informam as propriedades relatadas para cada módulo.

Cada manifesto de implantação requer dois módulos: $edgeAgent e $edgeHub. Estes módulos fazem parte do runtime IoT Edge que gere o dispositivo IoT Edge e os módulos que nele correm. Para mais informações sobre estes módulos, consulte Compreender o tempo de execução IoT Edge e a sua arquitetura.

Pode adicionar até 50 módulos adicionais para correr num dispositivo IoT Edge, além dos dois módulos de runtime.

Um manifesto de implementação que tenha apenas o tempo de execução IoT Edge ($edgeAgent e $edgeHub) é válido.

Os manifestos de implementação utilizam este formato:

{
  "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 runtime do IoT Edge instala os módulos na sua implementação. O agente IoT Edge é o componente de execução que gere a instalação, atualizações e relatórios de estado para um dispositivo IoT Edge. Assim, o $edgeAgent módulo gémeo tem a informação de configuração e gestão para todos os módulos. Esta informação inclui os parâmetros de configuração para o próprio agente IoT Edge.

As $edgeAgent propriedades usam este formato:

{
  "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 IoT Edge versão 1.1 foi lançado com a versão 1.0.10 do IoT Edge e permite definir a ordem de arranque dos módulos. Utilize a versão 1.1 do esquema para qualquer implementação do IoT Edge executando a versão 1.0.10 ou posterior.

Configuração e gestão de módulos

Defina quais os módulos que correm num dispositivo IoT Edge e como configurá-los e geri-los na lista de propriedades desejadas do agente IoT Edge.

Para uma lista completa das propriedades desejadas que pode ou deve incluir, consulte Propriedades do agente IoT Edge e IoT Edge hub.

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 mais informações, consulte Como configurar opções de criação de contentores para módulos de IoT Edge.

O módulo edgeHub e os módulos personalizados também têm três propriedades que indicam ao agente IoT Edge como os gerir:

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

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

• StartupOrder: Introduzido na versão IoT Edge 1.0.10. A ordem que o agente IoT Edge usa para iniciar os módulos quando são implementados 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 valor inicial porque começa sempre primeiro. Opcional.

  O agente IoT Edge inicia os módulos pela ordem do valor de arranque, mas não espera que cada módulo termine de começar antes de iniciar o seguinte.

  A ordem de inicialização ajuda se alguns módulos dependerem de outros. Por exemplo, pode querer que o módulo edgeHub comece primeiro para estar pronto a encaminhar mensagens quando os outros módulos começarem. 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 não alterares nenhuma propriedade do módulo, não é acionado o reinício do módulo.

Declarar rotas

O IoT Edge Hub gere a comunicação entre módulos, o IoT Hub e dispositivos a jusante. O módulo twin $edgeHub tem uma propriedade desejada chamada routes que define como as mensagens se movem dentro de uma implementaçã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 a versão 1.0.10 do IoT Edge e permite-lhe definir a priorização de rotas e o tempo de vida. Utilize a versão 1.1 do esquema para qualquer implementaçã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 encaminhar mensagens a partir de módulos ou dispositivos a jusante.

Ao utilizar os SDKs IoT, os módulos podem definir filas de saída específicas para as suas mensagens usando a ModuleClient classe. As filas de saída não são necessárias, mas ajudam a gerenciar várias rotas. Os dispositivos a jusante usam a classe DeviceClient nos SDKs IoT para enviar mensagens para dispositivos gateway IoT Edge, tal como enviam mensagens para o IoT Hub. Para mais informações, consulte Compreender e usar SDKs Azure IoT Hub.

A propriedade source pode usar qualquer um destes valores:

Condição

A condição é opcional em uma declaração de rota. Para passar todas as mensagens da fonte para o lavadouro, omita a cláusula WHERE . Ou, use a linguagem de consulta IoT Hub para filtrar mensagens ou tipos de mensagens que cumpram a condição. As rotas IoT Edge não suportam filtrar 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 os seus dispositivos e o Azure IoT Hub. Todas as mensagens usam o formato JSON e têm parâmetros systemProperties, appProperties e body .

Construa 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 encaminhar mensagens de dispositivos downstream diretamente para o IoT Hub e excluir mensagens de módulo, use esta rota:

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

Lavatório

O sumidouro define onde enviar mensagens. Apenas os módulos e o IoT Hub 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:

IoT Edge oferece garantias pelo menos uma vez. O hub IoT Edge armazena as mensagens localmente se uma rota não conseguir entregar a mensagem ao seu reservatório. Por exemplo, se o hub IoT Edge não conseguir ligar-se ao IoT Hub ou o módulo alvo não estiver ligado.

IoT Edge hub armazena mensagens até à hora definida na propriedade das propriedades desejadas do IoT Edge hub.

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 na versão 1.0.10 do IoT Edge com o esquema do 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. O sistema coloca as mensagens em fila nos seus endpoints. O sistema processa todas as mensagens de prioridade 0 para um endpoint específico antes de processar quaisquer mensagens de prioridade 1 para o mesmo endpoint. Se várias rotas para o mesmo endpoint tiverem a mesma prioridade, o sistema processa as mensagens pela ordem em que chegam. Se você não definir uma prioridade, a rota usará a prioridade mais baixa.

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

Para obter detalhes sobre como as filas de prioridade são geridas, veja Prioridade de rota e tempo de vida.

Definir ou atualizar as propriedades desejadas

O manifesto de implementaçã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 não definir as propriedades desejadas de um módulo gémeo no manifesto de implementação, o IoT Hub não altera o módulo gémeo. 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

• Para uma lista completa de propriedades que pode ou deve incluir em $edgeAgent e $edgeHub, consulte Propriedades do agente IoT Edge e IoT Edge hub.
• Agora que já sabes como funcionam os módulos IoT Edge, aprende sobre os requisitos e ferramentas para desenvolver módulos de IoT Edge.