Executar scripts em uma VM Windows usando a ação Executar Comandos
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.
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.
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/write. 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.
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.