Funções do PowerShell para IoT Edge para Linux no Windows

  • Artigo

Aplica-se a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

A versão com suporte é a IoT Edge 1.4. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Entenda as funções do PowerShell que implantam, provisionam e obtêm o status de seu IoT Edge para Linux na máquina virtual do Windows (EFLOW).

Pré-requisitos

Os comandos descritos neste artigo são do arquivo AzureEFLOW.psm1, que pode ser encontrado no seu sistema em seu diretório WindowsPowerShell em C:\Program Files\WindowsPowerShell\Modules\AzureEFLOW.

Se você não tiver a pasta AzureEflow em seu diretório do PowerShell, use as seguintes etapas para baixar e instalar o Azure IoT Edge para Linux no Windows:

  1. Em uma sessão do PowerShell com privilégios elevados, execute cada um dos comandos a seguir para baixar o IoT Edge para Linux no Windows.

    • X64/AMD64
    $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_X64" -OutFile $msiPath
    • ARM64
    $msiPath = $([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest "https://aka.ms/AzEFLOWMSI_1_4_LTS_ARM64" -OutFile $msiPath

  2. Instale o IoT Edge para Linux no Windows em seu dispositivo.

    Start-Process -Wait msiexec -ArgumentList "/i","$([io.Path]::Combine($env:TEMP, 'AzureIoTEdge.msi'))","/qn"

    Você pode especificar diretórios de instalação e VHDX personalizados adicionando os parâmetros INSTALLDIR="<FULLY_QUALIFIED_PATH>" e VHDXDIR="<FULLY_QUALIFIED_PATH>" ao comando de instalação.

  3. Defina a política de execução no dispositivo de destino como, pelo menos, AllSigned.

    Set-ExecutionPolicy -ExecutionPolicy AllSigned -Force

Add-EflowNetwork

O comando Add-EflowNetwork adiciona uma nova rede à máquina virtual EFLOW. Esse comando usa dois parâmetros.

Parâmetro Valores aceitos Comentários
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.
vswitchType Interno ou Externo Tipo do comutador virtual atribuído à VM EFLOW.

Ele retorna um objeto que contém quatro propriedades:

  • Nome
  • AllocationMethod
  • Cidr
  • Type

Para obter mais informações, use o comando Get-Help Add-EflowNetwork -full.

Add-EflowVmEndpoint

O comando Add-EflowVmEndpoint adiciona um novo ponto de extremidade de rede à máquina virtual EFLOW. Use os parâmetros opcionais para definir um IP estático.

Parâmetro Valores aceitos Comentários
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.
vendpointName Nome do ponto de extremidade virtual Nome do ponto de extremidade virtual atribuído à VM EFLOW.
ip4Address Endereço IPv4 no intervalo do escopo do servidor DHCP Endereço IPv4 estático da VM EFLOW.
ip4PrefixLength Comprimento do prefixo IPv4 da sub-rede Comprimento do prefixo IPv4 da sub-rede, válido somente quando o endereço IPv4 estático for especificado.
ip4GatewayAddress Endereço IPv4 do gateway de sub-rede Endereço IPv4 do gateway, válido somente quando o endereço IPv4 estático for especificado.

Ele retorna um objeto que contém quatro propriedades:

  • Nome
  • MacAddress
  • HealthStatus
  • IpConfiguration

Para obter mais informações, use o comando Get-Help Add-EflowVmEndpoint -full.

Add-EflowVmSharedFolder

O comando Add-EflowVmSharedFolder permite compartilhar uma ou mais pastas do sistema operacional host Windows com a máquina virtual do EFLOW.

Parâmetro Valores aceitos Comentários
sharedFoldersJsonPath String Caminho para o arquivo de configuração JSON Pastas Compartilhadas.

O arquivo de configuração JSON precisa ter a seguinte estrutura:

  • sharedFOlderRoot: caminho para a pasta raiz do Windows que contém todas as pastas a serem compartilhadas com a máquina virtual do EFLOW.
  • hostFolderPath: caminho relativo (para a pasta raiz pai) da pasta a ser compartilhada com a VM do EFLOW.
  • readOnly: define se a pasta compartilhada será gravável ou somente leitura para a máquina virtual do EFLOW – Valores: false ou true.
  • targetFolderOnGuest: caminho da pasta dentro da máquina virtual do EFLOW em que a pasta do sistema operacional host do Windows será montada.
[
   {
      "sharedFolderRoot": "<shared-folder-root-windows-path>",
      "sharedFolders": [ 
        { "hostFolderPath": "<path-shared-folder>", 
            "readOnly": "<read-only>", 
            "targetFolderOnGuest": "<linux-mounting-point>" 
        }
      ]
   }
]

Para obter mais informações, use o comando Get-Help Add-EflowVmSharedFolder -full.

Connect-EflowVm

O comando Connect-EflowVm se conecta à máquina virtual usando SSH. A única conta permitida para o SSH da máquina virtual é o usuário que a criou.

Esse comando funciona apenas em uma sessão do PowerShell em execução no dispositivo host. Ele não funcionará ao usar Windows Admin Center ou ISE do PowerShell.

Para obter mais informações, use o comando Get-Help Connect-EflowVm -full.

Copy-EflowVmFile

O comando Copy-EflowVmFile copia o arquivo de ou para a máquina virtual usando o SCP. Use os parâmetros opcionais para especificar os caminhos de arquivo de origem e de destino, bem como a direção da cópia.

O usuário iotedge-user deve ter permissão de leitura para qualquer diretório de origem ou permissão de gravação para qualquer diretório de destino na máquina virtual.

Parâmetro Valores aceitos Comentários
fromFile Cadeia de caracteres que representa o caminho para o arquivo Define o arquivo a ser lido.
toFile Cadeia de caracteres que representa o caminho para o arquivo Define o arquivo a ser gravado.
pushFile Nenhum Esse sinalizador indica a direção da cópia. Se estiver presente, o comando enviará o arquivo para a máquina virtual. Se estiver ausente, o comando efetuará pull do arquivo da máquina virtual.

Para obter mais informações, use o comando Get-Help Copy-EflowVMFile -full.

Deploy-Eflow

O comando Deploy-eFlow é o principal método de implantação. O comando de implantação cria a máquina virtual, provisiona arquivos e implanta o módulo agente do IoT Edge. Embora nenhum dos parâmetros seja necessário, eles podem ser usados para modificar as configurações da máquina virtual durante a criação.

Parâmetro Valores aceitos Comentários
acceptEula Sim ou Não Um atalho para aceitar/negar o EULA e ignorar o prompt do EULA.
acceptOptionalTelemetry Sim ou Não Um atalho para aceitar/negar telemetria opcional e ignorar o prompt de telemetria.
cpuCount Valor inteiro entre 1 e núcleos de CPU do dispositivo Número de núcleos de CPU para a VM.

Valor padrão: 1 vCore.
memoryInMB Valor inteiro par entre 1024 e a quantidade máxima de memória livre do dispositivo Memória alocada para a VM.

Valor padrão: 1.024 MB.
vmDiskSize Entre 21 GB e 2 TB Tamanho máximo do disco lógico do disco rígido virtual de expansão dinâmica.

Valor padrão: 29 GB.

Observação: vmDiskSize ou vmDataSize podem ser usados, mas não ambos juntos.
vmDataSize Entre 2 GB e 2 TB Tamanho máximo da partição de dados do disco rígido resultante, em GB.

Valor padrão: 10 GB.

Observação: vmDiskSize ou vmDataSize podem ser usados, mas não ambos juntos.
vmLogSize Pequeno ou Grande Especifica o tamanho da partição de log. Pequeno = 1 GB, Grande = 6 GB.

Valor padrão: pequeno.
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.
vswitchType Interno ou Externo Tipo do comutador virtual atribuído à VM EFLOW.
ip4Address Endereço IPv4 no intervalo do escopo do servidor DHCP Endereço IPv4 estático da VM EFLOW.
ip4PrefixLength Comprimento do prefixo IPv4 da sub-rede Comprimento do prefixo IPv4 da sub-rede, válido somente quando o endereço IPv4 estático for especificado.
ip4GatewayAddress Endereço IPv4 do gateway de sub-rede Endereço IPv4 do gateway, válido somente quando o endereço IPv4 estático for especificado.
gpuName Nome do dispositivo da GPU Nome do dispositivo da GPU a ser usado para passagem.
gpuPassthroughType DirectDeviceAssignment, ParaVirtualization ou nenhum (apenas CPU) Tipo de passagem de GPU
gpuCount Valor inteiro entre 1 e o número de núcleos da GPU do dispositivo Número de dispositivos da GPU para a VM.

Observação: se estiver usando ParaVirtualization, defina gpuCount = 1
customSsh Nenhum Determina se o usuário deseja usar a instalação personalizada do OpenSSH.Client. Se estiver presente, ssh.exe deverá estar disponível para o EFLOW PSM
sharedFoldersJsonPath String Caminho para o arquivo de configuração JSON Pastas Compartilhadas.

Para obter mais informações, use o comando Get-Help Deploy-Eflow -full.

Get-EflowHostConfiguration

O comando Get-EflowHostConfiguration retorna a configuração do host. Esse comando não usa parâmetros. Ele retorna um objeto que contém quatro propriedades:

  • FreePhysicalMemoryInMB
  • NumberOfLogicalProcessors
  • DiskInfo
  • GpuInfo

Para obter mais informações, use o comando Get-Help Get-EflowHostConfiguration -full.

Get-EflowLogs

O comando Get-EflowLogs coleta e agrupa logs do IoT Edge para Linux na implantação e instalação do Windows. Ele gera os logs agrupados na forma de uma pasta .zip.

Para obter mais informações, use o comando Get-Help Get-EflowLogs -full.

Get-EflowNetwork

O comando Get-EflowNetwork retorna uma lista das redes atribuídas à máquina virtual EFLOW. Use o parâmetro opcional para obter uma rede específica.

Parâmetro Valores aceitos Comentários
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.

Ele retorna uma lista de objetos que contém quatro propriedades:

  • Nome
  • AllocationMethod
  • Cidr
  • Type

Para obter mais informações, use o comando Get-Help Get-EflowNetwork -full.

Get-EflowVm

O comando Get-EflowVm retorna a configuração atual da máquina virtual. Esse comando não usa parâmetros. Ele retorna um objeto que contém quatro propriedades:

  • VmConfiguration
  • VmPowerState
  • EdgeRuntimeVersion
  • EdgeRuntimeStatus
  • SystemStatistics

Para exibir uma propriedade específica em uma lista acessível, execute o comando Get-EflowVM com a propriedade expandida. Por exemplo:

Get-EflowVM | Select -ExpandProperty VmConfiguration | Format-List

Para obter mais informações, use o comando Get-Help Get-EflowVm -full.

Get-EflowVmAddr

O comando Get-EflowVmAddr é usado para consultar os endereços IP e MAC da máquina virtual. Este comando existe para explicar o fato de que os endereços IP e MAC podem mudar com o tempo.

Para obter mais informações, use o comando Get-Help Get-EflowVmAddr -full.

Get-EflowVmEndpoint

O comando Get-EflowVmEndpoint retorna uma lista dos pontos de extremidade de rede atribuídos à máquina virtual EFLOW. Use o parâmetro opcional para obter um ponto de extremidade específico.

Parâmetro Valores aceitos Comentários
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.

Ele retorna uma lista de objetos que contém quatro propriedades:

  • Nome
  • MacAddress
  • HealthStatus
  • IpConfiguration

Para obter mais informações, use o comando Get-Help Get-EflowVmEndpoint -full.

Get-EflowVmFeature

O comando Get-EflowVmFeature retorna o status de habilitação da IoT Edge para Linux em recursos Windows.

Parâmetro Valores aceitos Comentários
recurso DpsTpm Nome do recurso a ser consultado.

Para obter mais informações, use o comando Get-Help Get-EflowVmFeature -full.

Get-EflowVmName

O comando Get-EflowVmName retorna o nome de host atual da máquina virtual. Esse comando existe por considerar o fato de que o nome de host do Windows pode ser alterado ao longo do tempo.

Para obter mais informações, use o comando Get-Help Get-EflowVmName -full.

Get-EflowVmSharedFolder

O comando Get-EflowVmSharedFolder retorna as informações sobre uma ou mais pastas do sistema operacional host Windows compartilhadas com a máquina virtual do EFLOW.

Parâmetro Valores aceitos Comentários
sharedfolderRoot String Caminho para a pasta raiz compartilhada do sistema operacional host Windows.
hostFolderPath Cadeia de caracteres ou lista Caminho/caminhos relativos (para a pasta raiz) para as pastas compartilhadas do sistema operacional host Windows.

Retorna uma lista de objetos que contém três propriedades:

  • hostFolderPath: caminho relativo (para a pasta raiz pai) da pasta compartilhada com a VM do EFLOW.
  • readOnly: define se a pasta compartilhada é gravável ou somente leitura para a máquina virtual do EFLOW – Valores: false ou true.
  • targetFolderOnGuest: caminho da pasta dentro da máquina virtual do EFLOW em que a pasta do Windows está montada.

Para obter mais informações, use o comando Get-Help Get-EflowVmSharedFolder -full.

Get-EflowVmTelemetryOption

O comando Get-EflowVmTelemetryOption exibe o status da telemetria (Opcional ou Obrigatório) dentro da máquina virtual.

Para obter mais informações, use o comando Get-Help Get-EflowVmTelemetryOption -full.

Get-EflowVmTpmProvisioningInfo

O comando Get-EflowVmTpmProvisioningInfo retorna as informações de provisionamento do TPM. Esse comando não usa parâmetros. Ele retorna um objeto que contém duas propriedades:

  • Chave de endosso
  • ID de registro

Para obter mais informações, use o comando Get-Help Get-EflowVmTpmProvisioningInfo -full.

Invoke-EflowVmCommand

O comando Invoke-EflowVMCommand executa um comando do Linux dentro da máquina virtual e retorna a saída. Esse comando só funciona para comandos do Linux que retornam uma saída finita. Ele não pode ser usado para comandos do Linux que exigem interação do usuário ou que são executados indefinidamente.

Os parâmetros opcionais a seguir podem ser usados para especificar o comando com antecedência.

Parâmetro Valores aceitos Comentários
. Cadeia de caracteres Comando a ser executado na VM.
ignoreError Nenhum Se esse sinalizador estiver presente, ignore os erros do comando.

Para obter mais informações, use o comando Get-Help Invoke-EflowVmCommand -full.

Provision-EflowVm

O comando Provision-EflowVm adiciona as informações de provisionamento para o dispositivo IOT Edge ao arquivo do IoT Edge da máquina virtual config.yaml.

Parâmetro Valores aceitos Comentários
provisioningType ManualConnectionString, ManualX509, DpsTPM, DpsX509, ou DpsSymmetricKey Define o tipo de provisionamento que você deseja usar para o dispositivo IoT Edge.
devConnString A cadeia de conexão de dispositivo de um dispositivo IoT Edge existente Cadeia de conexão do dispositivo para provisionamento manual de um dispositivo IoT Edge (ManualConnectionString).
iotHubHostname O nome do host de um hub IoT existente Nome do host do Hub IoT do Azure para provisionar um dispositivo IoT Edge (ManualX509).
deviceId A identificação do dispositivo de um dispositivo de IoT Edge existente ID do dispositivo para provisionar um dispositivo de IoT Edge (ManualX509).
scopeId A ID de escopo para uma instância de DPS existente. ID de escopo para provisionar um dispositivo de IoT Edge (DpsTPM, DpsX509 ou DpsSymmetricKey).
symmKey A chave primária para um registro de DPS existente ou a chave primária de um dispositivo de IoT Edge existente registrado usando chaves simétricas Chave simétrica para provisionar um dispositivo do IoT Edge (DpsSymmetricKey).
registrationId A ID de registro de um dispositivo de IoT Edge existente ID de registro para provisionar um dispositivo do IoT Edge (DpsSymmetricKey, DpsTPM).
identityCertPath Caminho do diretório Caminho de destino absoluto do certificado de identidade no computador host Windows (ManualX509, DpsX509).
identityPrivKeyPath Caminho do diretório Caminho de origem absoluto da chave privada de identidade em sua máquina host do Windows (ManualX509, DpsX509).
globalEndpoint URL do Ponto de Extremidade do Dispositivo URL do Ponto de Extremidade Global a ser usada para o provisionamento do DPS.

Para obter mais informações, use o comando Get-Help Provision-EflowVm -full.

Remove-EflowNetwork

O comando Remove-EflowNetwork remove uma rede existente anexada à máquina virtual EFLOW. Esse comando não usa parâmetros.

Parâmetro Valores aceitos Comentários
vswitchName Nome do comutador virtual Nome do comutador virtual atribuído à VM EFLOW.

Para obter mais informações, use o comando Get-Help Remove-EflowNetwork -full.

Remove-EflowVmEndpoint

O comando Remove-EflowVmEndpoint remove um ponto de extremidade de rede existente anexado à máquina virtual EFLOW. Esse comando não usa parâmetros.

Parâmetro Valores aceitos Comentários
vendpointName Nome do ponto de extremidade virtual Nome do ponto de extremidade virtual atribuído à VM EFLOW.

Para obter mais informações, use o comando Get-Help Remove-EflowVmEndpoint -full.

Remove-EflowVmSharedFolder

O comando Remove-EflowVmSharedFolder interrompe o compartilhamento da pasta do sistema operacional host Windows com a máquina virtual do EFLOW. Esse comando usa dois parâmetros.

Parâmetro Valores aceitos Comentários
sharedfolderRoot String Caminho para a pasta raiz compartilhada do sistema operacional host Windows.
hostFolderPath Cadeia de caracteres ou lista Caminho/caminhos relativos (para a pasta raiz) para as pastas compartilhadas do sistema operacional host Windows.

Para obter mais informações, use o comando Get-Help Remove-EflowVmSharedFolder -full.

Set-EflowVM

O comando Set-EflowVM atualiza a configuração da máquina virtual com as propriedades solicitadas. Use os parâmetros opcionais para definir uma configuração específica para a máquina virtual.

Parâmetro Valores aceitos Comentários
cpuCount Valor inteiro entre 1 e núcleos de CPU do dispositivo Número de núcleos de CPU para a VM.
memoryInMB Valor inteiro entre 1.024 e a quantidade máxima de memória livre do dispositivo Memória alocada para a VM.
gpuName Nome do dispositivo da GPU Nome do dispositivo da GPU a ser usado para passagem.
gpuPassthroughType DirectDeviceAssignment, ParaVirtualization ou nenhum (sem passagem) Tipo de passagem de GPU
gpuCount Valor inteiro entre 1 e núcleos da GPU do dispositivo Número de dispositivos da GPU para a VM Observação: válido somente ao usar DirectDeviceAssignment
headless Nenhum Se esse sinalizador estiver presente, ele determinará se o usuário precisa confirmar caso um aviso de segurança seja emitido.

Para obter mais informações, use o comando Get-Help Set-EflowVM -full.

Set-EflowVmDNSServers

O comando Set-EflowVmDNSServers configura os servidores DNS para a máquina virtual EFLOW.

Parâmetro Valores aceitos Comentários
vendpointName Valor da cadeia de caracteres do nome do ponto de extremidade virtual Use o Get-EflowVmEndpoint para obter as interfaces virtuais atribuídas à VM do EFLOW. Por exemplo, DESKTOP-CONTOSO-EflowInterface
dnsServers Lista de endereços IP do servidor DNS a ser usado para resolução de nomes Por exemplo, @("10.0.10.1")

Para obter mais informações, use o comando Get-Help Set-EflowVmDNSServers -full.

Set-EflowVmFeature

O comando Set-EflowVmFeature habilita ou desabilita o status do IoT Edge para Linux em recursos Windows.

Parâmetro Valores aceitos Comentários
recurso DpsTpm, Defender Nome do recurso a ser alternado.
enable Nenhum Se esse sinalizador estiver presente, o comando habilitará o recurso.

Para obter mais informações, use o comando Get-Help Set-EflowVmFeature -full.

Set-EflowVmTelemetryOption

O comando Set-EflowVmTelemetryOption habilita ou desabilita a telemetria opcional dentro da máquina virtual.

Parâmetro Valores aceitos Comentários
optionalTelemetry Verdadeiro ou falso Se a telemetria opcional está selecionada.

Para obter mais informações, use o comando Get-Help Set-EflowVmTelemetryOption -full.

Start-EflowVm

O comando Start-EflowVm inicia a máquina virtual. Se a máquina virtual já estiver iniciada, nenhuma ação será tomada.

Para obter mais informações, use o comando Get-Help Start-EflowVm -full.

Stop-EflowVm

O comando Stop-EflowVm interrompe a máquina virtual. Se a máquina virtual já estiver interrompida, nenhuma ação será tomada.

Para obter mais informações, use o comando Get-Help Stop-EflowVm -full.

Verify-EflowVm

O comando Verify-EflowVm é uma função exposta que verifica se o IoT Edge para Linux na máquina virtual Windows foi criado. Ele usa apenas parâmetros comuns e retornará Verdadeiro se a máquina virtual tiver sido criada e Falso se não tiver.

Para obter mais informações, use o comando Get-Help Verify-EflowVm -full.

Próximas etapas

Saiba como usar esses comandos para instalar e provisionar o IoT Edge para Linux no Windows no seguinte artigo: