Compartilhar via

Executar scripts em uma VM Windows usando a ação Executar Comandos

  • Artigo

O recurso Executar Comando usa o agente da máquina virtual (VM) para executar scripts do PowerShell dentro de uma VM Windows do Azure. Use esses scripts para o gerenciamento geral de máquinas ou aplicativos. Eles podem ajudá-lo a diagnosticar e corrigir rapidamente problemas de rede e acesso à VM e colocar a VM em um bom estado.

Benefícios

Acesse as máquinas virtuais de várias maneiras. O recurso Executar Comando pode executar scripts nas máquinas virtuais remotamente usando o agente de VM. Use Executar Comando por meio do portal do Azure, da API REST, ou do PowerShell para VMs do Windows.

Esse recurso é útil em todos os cenários em que você deseja executar um script em uma máquina virtual. É uma das únicas maneiras de solucionar problemas e corrigir uma máquina virtual que não tem a porta RDP ou SSH aberta devido à configuração imprópria da rede ou do usuário administrativo.

Pré-requisitos

Com suporte do SO do Windows

Sistema operacional Windows x64
Windows 10 Com suporte
Windows 11 Com suporte
Windows Server 2008 SP2 Com suporte
Windows Server 2008 R2 Com suporte
Windows Server 2012 Com suporte
Windows Server 2012 R2 Com suporte
Windows Server 2016 Com suporte
Windows Server 2016 Core Com suporte
Windows Server 2019 Com suporte
Windows Server 2019 Core Com suporte
Windows Server 2022 Com suporte
Windows Server 2022 Core Com suporte

Restrições

As seguintes restrições se aplicam ao usar o recurso Executar Comando:

  • A saída está limitada aos últimos 4.096 bytes.
  • O tempo mínimo para executar um script é de cerca de 20 segundos.
  • Os scripts são executados como sistema no Windows.
  • É possível executar um script por vez.
  • Scripts que solicitam informações (modo interativo) não têm suporte.
  • Não é possível cancelar um script em execução.
  • O tempo máximo que um script pode ser executado é 90 minutos. Depois disso, ele atingirá o tempo limite.
  • A conectividade de saída da VM é necessária para retornar os resultados do script.
  • Não é recomendável executar um script que causará uma parada ou atualização do Agente de VM. Isso pode permitir a extensão em um estado de Transição, levando a um tempo limite.

Observação

Para funcionar corretamente, Executar Comando requer conectividade (porta 443) a endereços IP públicos do Azure. Se a extensão não tiver acesso a esses pontos de extremidade, os scripts poderão ser executados com êxito, mas não retornarão os resultados. Se você estiver bloqueando o tráfego na máquina virtual, poderá usar marcas de serviço para permitir o tráfego para os endereços IP públicos do Azure usando a marca AzureCloud.

O recurso Executar Comando não funcionará se o status do agente de VM for NÃO ESTÁ PRONTO. Verifique o status do agente nas propriedades da VM no portal do Azure.

Comandos disponíveis

Esta tabela mostra a lista de comandos disponíveis para VMs Windows. Use o comando RunPowerShellScript para executar qualquer script personalizado que desejar. Quando você estiver usando a CLI do Azure ou o PowerShell para executar um comando, o valor fornecido para o parâmetro --command-id ou -CommandId deve ser um dos seguintes valores listados. Quando especifica um valor que não é um comando disponível, recebe este erro:

The entity was not found in this Azure location

Nome Descrição
RunPowerShellScript Executa um script do PowerShell
DisableNLA Desabilitar a autenticação no nível da rede
DisableWindowsUpdate Desabilitar atualizações automáticas do Windows Update
EnableAdminAccount Verifica se a conta de administrador local está desabilitada e, em caso positivo, a habilita.
EnableEMS Habilita o EMS
EnableRemotePS Configura o computador para habilitar o PowerShell remoto.
EnableWindowsUpdate Habilitar atualizações automáticas do Windows Update
IPConfig Mostra informações detalhadas do endereço IP, da máscara de sub-rede e do gateway padrão de cada adaptador associado ao TCP/IP.
RDPSettings Verifica as configurações do registro e de política de domínio. Sugere as ações de política se o computador fizer parte de um domínio ou modifica as configurações para os valores padrão.
ResetRDPCert Remove o certificado TSL/SSL associado ao ouvinte RDP e restaura a segurança dele para o padrão. Use este script se houver algum problema com o certificado.
SetRDPPort Define o padrão ou o número da porta do usuário especificado para conexões de Área de Trabalho Remota. Habilita as regras de firewall para acesso de entrada à porta.

CLI do Azure

O exemplo a seguir usa o comando az vm run-command para executar um script de shell em uma VM Windows do Azure.

# script.ps1
#   param(
#       [string]$arg1,
#       [string]$arg2
#   )
#   Write-Host This is a sample script with parameters $arg1 and $arg2

az vm run-command invoke  --command-id RunPowerShellScript --name win-vm -g my-resource-group \
    --scripts @script.ps1 --parameters "arg1=somefoo" "arg2=somebar"

Portal do Azure

Acesse uma VM no portal do Azure e selecione Executar comando no menu à esquerda, em Operações. Você vê uma lista dos comandos disponíveis a serem executados na VM.

Lista de comandos

Escolha um comando a ser executado. Alguns dos comandos podem ter parâmetros de entrada obrigatórios ou opcionais. Para esses comandos, os parâmetros são apresentados como campos de texto para você fornecer os valores de entrada. Para cada comando, é possível exibir o script que está em execução expandindo Exibir script. RunPowerShellScript é diferente dos outros comandos, uma vez que permite a você fornecer seu próprio script personalizado.

Observação

Os comandos internos não podem ser editados.

Depois de escolher o comando, selecione Executar para executar o script. Quando o script for concluído, ele retornará a saída e os erros na janela de saída. A captura de tela a seguir mostra um exemplo de saída da execução do comando RDPSettings.

Executar saída de script de comando

PowerShell

O exemplo a seguir usa o cmdlet Invoke-AzVMRunCommand para executar um script do PowerShell em uma VM do Azure. O cmdlet espera que o script referenciado no parâmetro -ScriptPath seja o local onde o cmdlet é executado.

Invoke-AzVMRunCommand -ResourceGroupName '<myResourceGroup>' -Name '<myVMName>' -CommandId 'RunPowerShellScript' -ScriptPath '<pathToScript>' -Parameter @{"arg1" = "var1";"arg2" = "var2"}

Observação

Os valores de parâmetro podem ser do tipo cadeia de caracteres somente e o script é responsável por convertê-los para outros tipos, se necessário.

Limitando o acesso ao recurso Executar Comando

Listar os comandos de execução ou mostrar os detalhes de um comando requer a permissão Microsoft.Compute/locations/runCommands/read no Nível de Assinatura. A função Leitor interna e os níveis superiores têm essa permissão.

A execução de um comando requer a permissão Microsoft.Compute/virtualMachines/runCommands/action. A função Colaborador de Máquina Virtual e os níveis superiores têm essa permissão.

Use uma das funções internas ou crie uma função personalizada para usar o recurso Executar Comando.

Solução de problemas do Windows para Ação Executar Comando

Ao solucionar problemas da ação executar comando para ambientes do Windows, confira o arquivo de log RunCommandExtension normalmente localizado no seguinte diretório: C:\WindowsAzure\Logs\Plugins\Microsoft.CPlat.Core.RunCommandWindows\<version>\RunCommandExtension.log, para obter mais detalhes.

Problemas conhecidos

  • A Extensão da Ação Executar Comando pode não ser executada no ambiente Windows, se o comando contiver caracteres reservados. Por exemplo:

    Se o símbolo & for passado no parâmetro do comando, como o script do PowerShell abaixo, ele poderá falhar.

    $paramm='abc&jj'
Invoke-AzVMRunCommand -ResourceGroupName AzureCloudService1 -Name test -CommandId 'RunPowerShellScript' -ScriptPath     C:\data\228332902\PostAppConfig.ps1 -Parameter @{"Prefix" = $paramm}

    Use o caractere ^ para sair do & no argumento, como $paramm='abc^&jj'

  • A extensão Executar Comando também pode não ser executada, se o comando a ser executado contiver "\n" no caminho, pois ela será tratada como uma nova linha. Por exemplo, C:\Windows\notepad.exe contém o \n no caminho do arquivo. Substitua \n por \N no caminho.

  • Verifique se você não tem nenhuma configuração personalizada na chave do Registro HKLM\SOFTWARE\Microsoft\Command Processor\AutoRun(detalhada aqui). Isso pode ser disparado durante a instalação da Extensão RunCommand ou habilitar fases e causar um erro como 'XYZ não é reconhecido como um comando interno ou externo, programa operável ou arquivo em lotes'.

Remoção da Ação Executar Comando

Se precisar remover a extensão do Windows da ação Executar Comando, confira as etapas abaixo para o Azure PowerShell e a CLI:

Substitua rgname e vmname pelo nome do grupo de recursos relevante e pelo nome da máquina virtual nos exemplos de remoção a seguir.

 Invoke-AzVMRunCommand -ResourceGroupName 'rgname' -VMName 'vmname' -CommandId 'RemoveRunCommandWindowsExtension'

az vm run-command invoke  --command-id RemoveRunCommandWindowsExtension --name vmname -g rgname

Observação

Ao aplicar Executar Comando novamente, a extensão será instalada automaticamente. Use o comando de remoção de extensão para solucionar problemas relacionados à extensão.

Próximas etapas

Para conhecer outras maneiras de executar scripts e comandos remotamente em sua VM, consulte Executar scripts na VM do Windows.