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

Aplica-se a: IoT Edge 1.1

Importante

A data de fim do suporte do IoT Edge 1.1 foi 13 de dezembro de 2022. Consulte o Ciclo de Vida de Produtos da Microsoft para obter informações sobre como é suportado este 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 completas para registrar e provisionar um dispositivo Windows IoT Edge.

Nota

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 usar o novo método para executar o IoT Edge em dispositivos Windows, Azure IoT Edge para Linux no Windows.

Se quiser usar o Azure IoT Edge para Linux no Windows, siga as etapas no guia de instruções equivalente.

Cada dispositivo que se conecta a um hub IoT tem um ID de dispositivo que é usado para rastrear comunicações de nuvem para dispositivo ou de dispositivo para nuvem. Você configura um dispositivo com suas informações de conexão, que incluem o nome do host do hub IoT, o ID 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, em que você conecta um único dispositivo ao seu hub IoT. Para provisionamento manual, você tem duas opções para autenticar dispositivos IoT Edge:

• Chaves simétricas: quando você cria uma nova identidade de dispositivo no Hub IoT, o serviço cria duas chaves. Você coloca uma das chaves no dispositivo e ela apresenta a chave para o Hub IoT ao autenticar.

  Este método de autenticação é mais rápido para começar, 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 de dispositivo no Hub IoT, você fornece impressões digitais de ambos os certificados. Quando o dispositivo se autentica 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 método de autenticação. Se você quiser usar certificados X.509, consulte Criar e provisionar um dispositivo IoT Edge no Windows usando certificados X.509.

Nota

Se você tiver muitos dispositivos para configurar e não quiser provisionar manualmente cada um, use um dos seguintes artigos para saber como o IoT Edge funciona com o serviço de provisionamento de dispositivos do Hub IoT:

• Crie e provisione dispositivos IoT Edge em escala usando certificados X.509
• Crie e provisione dispositivos IoT Edge em escala com um TPM
• Crie e provisione dispositivos IoT Edge em escala usando chaves simétricas

Pré-requisitos

Este artigo aborda o registro do dispositivo IoT Edge e a instalação do IoT Edge nele. Essas tarefas têm diferentes pré-requisitos e utilitários usados para realizá-las. Certifique-se de ter todos os pré-requisitos cobertos antes de prosseguir.

Ferramentas de gestão de dispositivos

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

Portal

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

Visual Studio Code

• Um hub IoT gratuito ou padrão em sua 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 em sua assinatura do Azure

• CLI do Azure em seu ambiente

  No mínimo, sua versão da CLI do Azure deve ser 2.0.70 ou mais recente. Utilize az --version para validar. Esta versão suporta comandos de extensão az e apresenta a arquitetura de comandos Knack.

Requisitos do dispositivo

Um dispositivo Windows.

O IoT Edge com contêineres do Windows requer a versão 1809/build 17763 do Windows, que é a compilação de suporte de longo prazo mais recente do Windows. Certifique-se de revisar a lista de sistemas suportados para obter uma lista de SKUs suportados.

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 a incompatibilidade do sistema operacional.

Registar o seu dispositivo

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

Portal

Em seu hub IoT no portal do Azure, os dispositivos IoT Edge são criados e gerenciados separadamente dos dispositivos IoT que não estão habilitados para borda.

1. Entre no portal do Azure e navegue até seu hub IoT.

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

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

   • Crie um ID de dispositivo descritivo. Anote este ID do dispositivo, pois irá utilizá-lo mais tarde.
   • Marque a caixa de seleção Dispositivo IoT Edge.
   • Selecione Chave simétrica como o tipo de autenticação.
   • Use as configurações padrão para gerar automaticamente chaves de autenticação e conectar o novo dispositivo ao hub.

4. Selecione Guardar.

Visual Studio Code

Inicie sessão para aceder ao seu hub IoT

Você pode usar as extensões do Azure IoT para Visual Studio Code para executar operações com seu hub IoT. Para que essas operações funcionem, você precisa entrar em sua conta do Azure e selecionar seu hub.

1. No Visual Studio Code, abra o modo de exibição Explorer .

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

   

3. Clique no cabeçalho da seção ... no cabeçalho da seção Hub IoT do Azure. Se não vir as reticências, clique ou passe o cursor sobre o cabeçalho.

4. Escolha Selecionar Hub IoT.

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

6. Selecione a subscrição do Azure.

7. Selecione seu hub IoT.

Registrar um novo dispositivo com o Visual Studio Code

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

Na tela de saída, você vê o resultado do comando. As informações do dispositivo são impressas, o que inclui o deviceId que você forneceu e o connectionString que você pode 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 em seu 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: Forneça um nome descritivo exclusivo dentro do seu hub IoT.

• --hub-name ou -n: Forneça o nome do seu hub IoT.

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

  

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

Exibir dispositivos registrados e recuperar informações de provisionamento

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

Portal

Os dispositivos habilitados para borda que se conectam ao seu hub IoT estão listados na página Dispositivos . Você pode filtrar a lista por tipo Iot Edge Device.

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

Os dispositivos que se autenticam com chaves simétricas têm suas cadeias de conexão disponíveis para cópia no portal.

1. Na página Dispositivos no portal, selecione o ID do dispositivo IoT Edge na lista.
2. Copie o valor de Cadeia de Conexão Primária ou Cadeia de Conexão Secundária.

Visual Studio Code

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

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

1. Clique com o botão direito do rato no ID do seu dispositivo na secção Hub IoT do Azure.

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

   A cadeia de conexão é copiada para a área de transferência.

Você também pode selecionar Obter informações do dispositivo no menu do botão direito do mouse 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 em seu hub IoT. Por exemplo:

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

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

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

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

Gorjeta

O connection-string show comando foi introduzido na versão 0.9.8 da extensão do Azure IoT, substituindo o comando preterido show-connection-string . Se você receber um 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 atualizações mais recentes, consulte Extensão do Microsoft Azure IoT para CLI do Azure.

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

Ao copiar a cadeia de conexão para usar em um dispositivo, não inclua as aspas ao redor da cadeia de conexão.

Instalar o IoT Edge

Nesta seção, você prepara sua VM do Windows ou dispositivo físico para o IoT Edge. Em seguida, instale o IoT Edge.

O Azure IoT Edge depende de um tempo de execução de contêiner compatível com OCI. 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 tempo de execução do IoT Edge:

1. Execute o PowerShell como um administrador.

   Use uma sessão AMD64 do PowerShell, não o PowerShell(x86). Se não tiver certeza de qual tipo de sessão 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 a sua máquina Windows está numa versão suportada
   • Ativa o recurso de contêineres
   • Baixa o mecanismo moby e o tempo de execução 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, você pode usar parâmetros adicionais para modificar o processo, incluindo:

• Tráfego direto para passar por um servidor proxy
• Aponte 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 sua identidade na nuvem

Agora que o mecanismo de contêiner e o tempo de execução do IoT Edge estão instalados em seu dispositivo, você está pronto para a próxima etapa, que é configurar o dispositivo com sua identidade na nuvem e informações de autenticação.

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

2. Use o comando Initialize-IoTEdge para configurar o tempo de execução do IoT Edge em sua máquina. O comando assume 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ê baixou o script IoTEdgeSecurityDaemon.ps1 em seu dispositivo para instalação offline ou de versão específica, 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. A cadeia de conexão do dispositivo associa o dispositivo físico a um ID de dispositivo no Hub IoT e fornece informações de autenticação.

   A cadeia de conexão do dispositivo tem 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, você pode usar parâmetros adicionais para modificar o processo, incluindo:

• Tráfego direto para passar por um servidor proxy
• Declare uma imagem de contêiner edgeAgent específica e forneça credenciais se ela estiver em 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 a configuração bem-sucedida

Verifique se o tempo de execução foi instalado e configurado com êxito em seu dispositivo IoT Edge.

Verifique o estado do serviço IoT Edge.

Get-Service iotedge

Examine os logs de serviço.

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

Listar módulos em execução.

iotedge list

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

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

• Instalar o IoT Edge enquanto estiver offline
• Instalar uma 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
• Cabine do Microsoft Azure IoT Edge, que contém o daemon de segurança do IoT Edge (iotedged), o mecanismo de contêiner Moby e a CLI do Moby
• Instalador do pacote redistribuível do Visual C++ (VC runtime)

Se o seu dispositivo estiver offline durante a instalação ou se pretender instalar uma versão específica do IoT Edge, pode transferir estes ficheiros antecipadamente para o dispositivo. Na hora de instalar, aponte o script de instalação para o diretório que contém os arquivos baixados. O instalador verifica primeiro esse diretório e, em seguida, só baixa os componentes que não foram encontrados. Se todos os ficheiros estiverem disponíveis offline, pode instalar sem ligação à Internet.

1. Para obter os arquivos de instalação mais recentes do IoT Edge juntamente com versões anteriores, consulte Versões do Azure IoT Edge.

2. Encontre a versão que deseja instalar 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 de lançamento 1.1.

   É importante usar o script do PowerShell da mesma versão que o arquivo de .cab que você usa, pois a funcionalidade é alterada para dar suporte aos recursos em cada versão.

3. Se o arquivo .cab que você baixou tiver um sufixo de arquitetura, renomeie o arquivo 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. Salve o instalador na mesma pasta em seu dispositivo IoT que os arquivos do IoT Edge.

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

6. Execute o comando Deploy-IoTEdge com o -OfflineInstallationPath parâmetro. 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 deployment usará todos os componentes encontrados no diretório de arquivo local fornecido. Se o arquivo .cab ou o instalador do Visual C++ estiver faltando, ele tentará baixá-los.

Desinstalar o IoT Edge

Se você quiser remover a instalação do IoT Edge do seu dispositivo Windows, use o comando Uninstall-IoTEdge de uma janela administrativa do PowerShell. Este comando remove o tempo de execução 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 opções de desinstalação, use o comando Get-Help Uninstall-IoTEdge -full.

Próximos passos

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