Criar e provisionar um dispositivo IoT Edge de Windows usando chaves simétricas

Aplica-se a: IoT Edge 1.1

Importante

IoT Edge 1.1 a data de término do suporte foi 13 de dezembro de 2022. Confira o Ciclo de Vida do Produto da Microsoft para obter informações sobre o suporte deste produto, serviço, tecnologia ou API. Para obter mais informações sobre como atualizar para a versão mais recente do IoT Edge, consulte Atualizar o IoT Edge.

Este artigo fornece instruções de ponta a ponta para registrar e provisionar um Windows IoT Edge dispositivo.

Observação

O Azure IoT Edge com contêineres do Windows não terá suporte a partir da versão 1.2 do Azure IoT Edge.

Considere o uso do novo método para executar o IoT Edge em dispositivos Windows, Azure IoT Edge para Linux no Windows.

Se você quiser usar o Azure IoT Edge para Linux no Windows, poderá seguir as etapas no guia de instruções equivalente.

Cada dispositivo que se conecta a um hub IoT tem uma identidade do dispositivo que é usada para controlar as comunicações da nuvem para dispositivo ou do dispositivo para nuvem. Você configura um dispositivo com suas informações de conexão, o que inclui o nome do host do hub IoT, a identidade do dispositivo e as informações que o dispositivo usa para autenticar no Hub IoT.

As etapas neste artigo percorrem um processo chamado provisionamento manual, no qual você conecta um único dispositivo ao seu hub IoT. No provisionamento manual, você tem duas opções para autenticar dispositivos do IoT Edge:

• Chaves simétricas: quando você cria uma identidade do dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e apresenta a chave para o Hub IoT durante a autenticação.

  Esse método de autenticação é mais rápido para começar a usar, mas não tão seguro.

• X.509 autoassinado: você cria dois certificados de identidade X.509 e os coloca no dispositivo. Ao criar uma nova identidade do dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo é autenticado no Hub IoT, ele apresenta um certificado e o Hub IoT verifica se o certificado corresponde à sua impressão digital.

  Esse método de autenticação é mais seguro e recomendado para cenários de produção.

Este artigo aborda o uso de chaves simétricas como seu método de autenticação. Se você quiser usar certificados X.509, confira Criar e provisionar um dispositivo IoT Edge no Windows usando certificados x. 509.

Observação

Se você tiver muitos dispositivos a serem configurados e não quiser provisionar manualmente cada um deles, use um dos artigos a seguir para saber como IoT Edge funciona com o Serviço de Provisionamento de Dispositivos no Hub IoT:

• Criar e provisionar dispositivos de Azure IoT Edge em escala usando certificados X.509
• Criar e provisionar dispositivos do IoT Edge em escala com um TPM
• Criar e provisionar dispositivos de Azure IoT Edge em escala usando chaves simétricas

Pré-requisitos

Este artigo aborda o registro do dispositivo do IoT Edge e a instalação do IoT Edge nesse dispositivo. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de que você tenha todos os pré-requisitos listados antes de continuar.

Ferramentas de gerenciamento de dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure nas etapas para registrar o dispositivo. Cada utilitário tem pré-requisitos próprios:

Portal

Um hub IoT gratuito ou padrão na assinatura do Azure.

Visual Studio Code

• Um hub IoT gratuito ou padrão na assinatura do Azure
• Visual Studio Code
• Extensão do Hub IoT do Azure
• Azure IoT Edge para Visual Studio Code

CLI do Azure

• Um hub IoT gratuito ou padrão na assinatura do Azure

• CLI do Azure em seu ambiente

  No mínimo, a versão da CLI do Azure deve ser 2.0.70 ou mais recente. Use az --version para validar. Esta versão dá suporte aos comandos da extensão az e introduz a estrutura de comandos Knack.

Requisitos do dispositivo

Um dispositivo Windows.

O IoT Edge com contêineres do Windows requer o Windows versão 1809/compilação 17763, que é a compilação de suporte de longo prazo do Windows mais recente. Não deixe de revisar a lista de sistemas com suporte para ver uma lista de SKUs com suporte.

Observe que as versões do Windows no contêiner e no host devem corresponder. Para obter mais informações, consulte Não foi possível iniciar o módulo devido à incompatibilidade do sistema operacional.

Registre seu dispositivo

Você pode usar o portal do Azure, o Visual Studio Code ou a CLI do Azure para registrar seu dispositivo, dependendo da preferência.

Portal

No hub IoT do portal do Azure, os dispositivos do IoT Edge são criados e gerenciados separadamente dos dispositivos de IoT que não são habilitados para a borda.

1. Entre no Portal do Azure e navegue até o Hub IoT.

2. No painel esquerdo, selecione Dispositivos no menu e, em seguida, Adicionar dispositivo.

3. Na página Criar um dispositivo, forneça as seguintes informações:

   • Crie uma ID do dispositivo descritivo. Anote a identidade desse dispositivo, pois você a usará depois.
   • Marque a caixa de seleção Dispositivo do IoT Edge.
   • Selecione Chave simétrica como o tipo de autenticação.
   • Use as configurações padrão para gerar automaticamente as chaves de autenticação e conectar o novo dispositivo ao hub.

4. Clique em Salvar.

Visual Studio Code

Entre para acessar o Hub IoT

É possível usar as extensões do Azure IoT para Visual Studio Code para executar operações com o Hub IoT. Para que essas operações funcionem, é necessário entrar na conta do Azure e selecionar o hub.

1. No Visual Studio Code, abra a exibição do Explorer.

2. Na parte inferior do Explorer, expanda a seção Hub IoT.

   

3. Clique em ... no cabeçalho da seção Hub IoT. Se você não visualizar as reticências, clique ou passe o mouse sobre o cabeçalho.

4. Escolha Selecionar Hub IoT.

5. Se não estiver conectado à conta do Azure, siga as instruções para fazer isso.

6. Selecione sua assinatura do Azure.

7. Selecione seu Hub IoT.

Registrar um novo dispositivo com o Visual Studio Code

1. No Explorer do Visual Studio Code, expanda a seção Hub IoT do Azure.
2. Clique em ... no cabeçalho da seção Hub IoT. Se você não visualizar as reticências, clique ou passe o mouse sobre o cabeçalho.
3. Selecione Criar dispositivo IoT Edge.
4. Na caixa de texto que abrir, dê a seu dispositivo um ID.

Na tela de saída, você verá o resultado do comando. A informação do dispositivo é impressa, o que inclui o deviceId que você forneceu e o connectionString que você consegue usar para conectar seu dispositivo físico ao Hub IoT.

CLI do Azure

Use o comando az iot hub device-identity create para criar uma nova identidade de dispositivo no hub IoT. Por exemplo:

az iot hub device-identity create --device-id device_id_here --hub-name hub_name_here --edge-enabled

Este comando inclui três parâmetros:

• --device-id ou -d: fornece um nome descritivo exclusivo no hub IoT.

• --hub-name ou -n: fornece o nome do hub IoT.

• --edge-enabled ou --ee: declara que o dispositivo é um dispositivo do IoT Edge.

  

Agora que você tem um dispositivo registrado no Hub IoT, recupere as informações que você usa para concluir a instalação e o provisionamento do runtime do IoT Edge.

Exibir dispositivos registrados e recuperar informações de provisionamento

Os dispositivos que usam a autenticação de chave simétrica precisam de suas cadeias de conexão para concluir a instalação e o provisionamento do runtime do IoT Edge.

Portal

Todos os dispositivos habilitados para borda que se conectam ao hub IoT são listados na página Dispositivos. Você pode filtrar a lista por tipo de Dispositivo do Iot Edge.

Quando estiver pronto para configurar o dispositivo, você precisará da cadeia de conexão que vincula o dispositivo físico à identidade no hub IoT.

As cadeias de conexão dos dispositivos que se autenticam com chaves simétricas estão disponíveis para cópia no portal.

1. Na página Dispositivos no portal, selecione a identificação do dispositivo IoT Edge na lista.
2. Copie o valor da Cadeia de conexão primária ou Cadeia de conexão secundária.

Visual Studio Code

Todos os dispositivos que conectam ao seu Hub IoT estão listados na seção Azure IoT Hub do Visual Studio Code Explorer. Os dispositivos do IoT Edge são distinguidos dos dispositivos que não são de borda por um ícone diferente e pelo fato de que os módulos $edgeAgent e $edgeHub são implantados em cada dispositivo do IoT Edge.

Quando estiver pronto para configurar o dispositivo, você precisará da cadeia de conexão que vincula o dispositivo físico à identidade no hub IoT.

1. Clique com o botão direito na ID do seu dispositivo na seção Hub IoT.

2. Selecione Copiar cadeia de conexão de dispositivo.

   A cadeia de conexão é copiada à sua área de transferência.

Você também pode selecionar Pegar Informação do Dispositivo do menu de botão direito para ver todas as informações do dispositivo, incluindo a cadeia de conexão, na janela de saída.

CLI do Azure

Use o comando az iot hub device-identity list para exibir todos os dispositivos no hub IoT. Por exemplo:

az iot hub device-identity list --hub-name hub_name_here

Qualquer dispositivo registrado como um dispositivo do IoT Edge terá a propriedade capabilities.iotEdge definida para true.

Quando estiver pronto para configurar o dispositivo, você precisará da cadeia de conexão que vincula o dispositivo físico à identidade no hub IoT. Use o comando az iot hub device-identity connection-string show para retornar a cadeia de conexão para um único dispositivo:

az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]

Dica

O comando connection-string show foi introduzido na versão 0.9.8 da extensão do Azure IoT, substituindo o comando show-connection-string preterido. Se você receber uma mensagem de erro ao executar esse comando, verifique se a versão da extensão está atualizada para 0.9.8 ou posterior. Para obter mais informações e as últimas atualizações, consulte Extensão do Microsoft Azure IoT para a CLI do Azure.

O valor para o parâmetro device-id diferencia maiúsculas de minúsculas.

Ao copiar a cadeia de conexão a ser usada em um dispositivo, não inclua aspas na cadeia de conexão.

Instalar o Edge IoT

Nesta seção, você preparará a VM ou o dispositivo físico Windows para o IoT Edge. Em seguida, você instalará o IoT Edge.

O Azure IoT Edge depende de um runtime de contêiner compatível com OCI. O Moby, um mecanismo baseado em Moby, está incluído no script de instalação, o que significa que não há etapas adicionais para instalar o mecanismo.

Para instalar o runtime do Azure IoT Edge:

1. Execute o PowerShell como administrador.

   Use uma sessão AMD64 do PowerShell, não o PowerShell(x86). Para saber qual tipo de sessão você está usando, execute o seguinte comando:

   (Get-Process -Id $PID).StartInfo.EnvironmentVariables["PROCESSOR_ARCHITECTURE"]
   

2. Execute o comando Deploy-IoTEdge, que executa as seguintes tarefas:

   • Verifica se o computador Windows está em uma versão compatível
   • Ativa o recurso de contêineres
   • Baixa o mecanismo Moby e o runtime do IoT Edge

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Deploy-IoTEdge
   

3. Reinicie o dispositivo, se solicitado.

Ao instalar o IoT Edge em um dispositivo, é possível usar parâmetros adicionais para modificar o processo, incluindo:

• Tráfego direto para passar por um servidor proxy
• Apontar o instalador para um diretório local para instalação offline

Para obter mais informações sobre esses parâmetros adicionais, consulte Scripts do PowerShell para IoT Edge com contêineres do Windows.

Provisionar o dispositivo com a identidade de nuvem dele

Agora que o mecanismo de contêiner e o runtime do IoT Edge estão instalados no dispositivo, você está pronto para a próxima etapa, que consiste na configuração do dispositivo com a identidade de nuvem e as informações de autenticação dele.

1. No dispositivo IoT Edge, execute o PowerShell como administrador.

2. Use o comando Initialize-IoTEdge para configurar o runtime do IoT Edge no computador. O comando assumirá como padrão o provisionamento manual com contêineres do Windows.

   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
   Initialize-IoTEdge -ManualConnectionString -ContainerOs Windows
   

   • Se você tiver baixado o script IoTEdgeSecurityDaemon.ps1 em seu dispositivo para uma instalação de versão específica ou offline, certifique-se de fazer referência à cópia local do script.

     . <path>/IoTEdgeSecurityDaemon.ps1
     Initialize-IoTEdge -ManualConnectionString -ContainerOs Windows
     

3. Quando solicitado, forneça a cadeia de conexão do dispositivo recuperada na seção anterior. Ela associa o dispositivo físico a uma ID de dispositivo no Hub IoT e fornece informações de autenticação.

   A cadeia de conexão do dispositivo usa o seguinte formato e não deve incluir aspas: HostName={IoT_hub_name}.azure-devices.net;DeviceId={device_name};SharedAccessKey={key}

Ao provisionar um dispositivo manualmente, é possível usar parâmetros adicionais para modificar o processo, incluindo:

• Tráfego direto para passar por um servidor proxy
• Declarar uma imagem de contêiner edgeAgent específica e fornecer credenciais no caso de um registro privado

Para obter mais informações sobre esses parâmetros adicionais, consulte Scripts do PowerShell para IoT Edge com contêineres do Windows.

Verificar configuração bem-sucedida

Verifique se o runtime foi instalado e configurado com êxito em seu dispositivo IoT Edge.

Verifique o status do serviço do IoT Edge.

Get-Service iotedge

Examine os logs de serviço.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog

Módulos de execução da lista.

iotedge list

Instalação offline ou de versão específica (opcional)

As etapas nesta seção são destinadas a cenários não cobertos pelas etapas de instalação padrão. Isso pode incluir:

• Instalar o IoT Edge offline
• Instalar a versão Release Candidate
• Instalar uma versão diferente da mais recente

Durante a instalação, três arquivos são baixados:

• Um script do PowerShell, que contém as instruções de instalação
• O CAB do Microsoft Azure IoT Edge, que contém o daemon de segurança (iotedged) do IoT Edge, o mecanismo de contêiner Moby e a CLI do Moby
• Instalador do pacote redistribuível do Visual C++ (runtime de VC)

Se o dispositivo ficar offline durante a instalação ou você quiser instalar uma versão específica do IoT Edge, baixe esses arquivos antecipadamente no dispositivo. Quando for o momento da instalação, aponte o script de instalação para o diretório que contém os arquivos baixados. O instalador primeiro verifica o diretório e, em seguida, baixa somente os componentes não localizados. Se todos os arquivos estiverem disponíveis offline, será possível instalá-los sem conexão com a Internet.

1. Para obter os arquivos de instalação mais recentes do IoT Edge e as versões anteriores, consulte Lançamentos do Azure IoT Edge.

2. Localize a versão que será instalada e baixe os seguintes arquivos da seção Ativos das notas de versão para seu dispositivo IoT:

   • IoTEdgeSecurityDaemon.ps1
   • Microsoft-Azure-IoTEdge-amd64.cab do canal da versão 1.1.

   É importante usar o script do PowerShell na mesma versão do arquivo .cab usado, pois a funcionalidade muda para dar suporte aos recursos em cada versão.

3. Se o arquivo .cab baixado tiver um sufixo de arquitetura, renomeie-o para apenas Microsoft-Azure-IoTEdge.cab.

4. Opcionalmente, baixe um instalador para Visual C++ redistribuível. Por exemplo, o script do PowerShell usa esta versão: vc_redist.x64.exe. Em seu dispositivo IoT, salve o instalador na mesma pasta dos arquivos do IoT Edge.

5. Para instalar com componentes offline, efetue dot source na cópia local do script do PowerShell.

6. Execute o comando Deploy-IoTEdge com o parâmetro -OfflineInstallationPath. Forneça o caminho absoluto para o diretório de arquivos. Por exemplo,

   . path_to_powershell_module_here\IoTEdgeSecurityDaemon.ps1
   Deploy-IoTEdge -OfflineInstallationPath path_to_file_directory_here
   

   O comando de implantação usará todos os componentes encontrados no diretório de arquivos local fornecido. Se o arquivo .cab ou o instalador do Visual C++ estiverem ausentes, ele tentará baixá-los.

Desinstalar o IoT Edge

Para remover a instalação do IoT Edge do dispositivo Windows, use o comando Uninstall-IoTEdge em uma janela administrativa do PowerShell. Esse comando remove o runtime do IoT Edge, juntamente com a configuração existente e os dados do mecanismo Moby.

. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; `
Uninstall-IoTEdge

Para obter mais informações sobre as opções de desinstalação, use o comando Get-Help Uninstall-IoTEdge -full.

Próximas etapas

Prossiga para implantar módulos do IoT Edge para saber como implantar módulos em seu dispositivo.