Executar scripts em sua VM do Windows usando Executar Comando gerenciado

Artigo
10/15/2024

Aplica-se a: ✔️ VMs do Windows ✔️ Conjuntos de dimensionamento flexíveis

Importante

No momento, o Comando de Execução Gerenciada está disponível na CLI do Azure, no PowerShell e na API. A funcionalidade do portal estará disponível em breve.

O recurso Executar comando usa o agente de máquina virtual (VM) para executar scripts em uma VM do 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.

Executar Comando gerenciado atualizado usa o mesmo canal do agente de VM para executar scripts e fornece os seguintes aprimoramentos sobre Executar Comando orientado a ação original:

Suporte para Executar Comando atualizado por meio do modelo de implantação de ARM
Execução paralela de vários scripts
Execução sequencial de scripts
Tempo limite de script especificado pelo usuário
Suporte para scripts de execução prolongada (horas/dias)
Passando segredos (parâmetros, senhas) de maneira segura

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

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/runCommand/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.

CLI do Azure

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

Executar um script com a VM

Esse comando fornecerá o script para a VM, o executará e retornará a saída capturada.

az vm run-command create --name "myRunCommand" --vm-name "myVM" --resource-group "myRG" --script "Write-Host Hello World!"

Listar todos os recursos de RunCommand implantados em uma VM

Esse comando retornará uma lista completa de Executar Comando implantados anteriormente juntamente com suas propriedades.

az vm run-command list --vm-name "myVM" --resource-group "myRG"

Obter resultados e status da execução

Esse comando recuperará o andamento da execução atual, incluindo a saída mais recente, a hora de início/término, o código de saída e o estado terminal da execução.

az vm run-command show --name "myRunCommand" --vm-name "myVM" --resource-group "myRG" --expand instanceView

Observação

Os campos de saída e erro em instanceView são limitados aos últimos 4KB. Se você quiser acessar a saída e o erro completos, terá a opção de encaminhar os dados de saída e do erro para blobs de acréscimo de armazenamento usando os parâmetros -outputBlobUri e -errorBlobUri enquanto executa Executar Comando usando Set-AzVMRunCommand ou Set-AzVMssRunCommand.

Excluir o recurso RunCommand da VM

Remova o recurso RunCommand implantado anteriormente na VM. Se a execução do script ainda estiver em andamento, a execução será encerrada.

az vm run-command delete --name "myRunCommand" --vm-name "myVM" --resource-group "myRG"

PowerShell

Executar um script com a VM

Esse comando fornecerá o script para a VM, o executará e retornará a saída capturada.

Set-AzVMRunCommand -ResourceGroupName "myRG" -VMName "myVM" -Location "EastUS" -RunCommandName "RunCommandName" –SourceScript "echo Hello World!"

Executar um script na VM usando o parâmetro SourceScriptUri

OutputBlobUri e ErrorBlobUri são parâmetros opcionais.

Set-AzVMRunCommand -ResourceGroupName "myRg" `
-VMName "myVM" `
-RunCommandName "RunCommandName" `
-SourceScriptUri “<SAS_URI_of_a_storage_blob_with_read_access_or_public_URI>" `
-OutputBlobUri “<SAS_URI_of_a_storage_append_blob_with_read_add_create_write_access>" `
-ErrorBlobUri “<SAS_URI_of_a_storage_append_blob_with_read_add_create_write_access>”

Listar todos os recursos de RunCommand implantados em uma VM

Esse comando retornará uma lista completa de Executar Comando implantados anteriormente juntamente com suas propriedades.

Get-AzVMRunCommand -ResourceGroupName "myRG" -VMName "myVM"

Obter resultados e status da execução

Esse comando recuperará o andamento da execução atual, incluindo a saída mais recente, a hora de início/término, o código de saída e o estado terminal da execução.

Get-AzVMRunCommand -ResourceGroupName "myRG" -VMName "myVM" -RunCommandName "RunCommandName" -Expand InstanceView

Criar ou atualizar Executar Comando em uma VM usando SourceScriptUri (URL SAS do blob de armazenamento)

Crie ou atualize Executar Comando em uma VM do Windows usando uma URL SAS de um blob de armazenamento que contenha um script do PowerShell. SourceScriptUri pode ser a URL SAS completa ou a URL pública de um blob de armazenamento.

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVMEE -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri>

Observação

A URL SAS deve fornecer acesso de leitura ao blob. Um tempo de expiração de 24 horas é sugerido para a URL SAS. As URLs SAS podem ser geradas no portal do Azure usando as opções do blob ou o token SAS usando New-AzStorageBlobSASToken. Se estiver gerando token SAS usando New-AzStorageBlobSASToken, o URL SAS = "URL de blob base" + "?" + "token SAS de New-AzStorageBlobSASToken"

Obter um modo de exibição de instância de Executar Comando para uma VM após criar ou atualizar Executar Comando

Obtenha um Executar Comando para VM com Exibição de Instância. A Exibição de Instância contém o estado de execução de Executar Comando (Êxito, Com Falha etc.), código de saída, saída padrão e erro padrão gerados pela execução do script usando Executar Comando. Um ExitCode diferente de zero indica uma execução malsucedida.

$x = Get-AzVMRunCommand -ResourceGroupName MyRG -VMName MyVM -RunCommandName MyRunCommand -Expand InstanceView
$x.InstanceView

Saída de exemplo

ExecutionState   : Succeeded
ExecutionMessage :
ExitCode         : 0
Output           :   
output       : uid=0(root) gid=0(root) groups=0(root)
                   HelloWorld

Error            :
StartTime        : 10/27/2022 9:10:52 PM
EndTime          : 10/27/2022 9:10:55 PM
Statuses         :

InstanceView.ExecutionState: status do script Executar Comando do usuário. Consulte esse estado para saber se o script foi bem-sucedido ou não. ProvisioningState: status do provisionamento de extensão geral de ponta a ponta (se a plataforma de extensão foi capaz de disparar o script Executar Comando ou não).

Criar ou atualizar Executar Comando em uma VM usando ScriptLocalPath (arquivo de script local)

Crie ou atualize Executar Comando em uma VM usando um arquivo de script local que está no computador cliente em que o cmdlet é executado.

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVMEE -RunCommandName MyRunCommand -Location EastUS2EUAP -ScriptLocalPath "C:\MyScriptsDir\MyScript.ps1"

Criar ou atualizar Executar Comando em uma VM usando SourceScript (texto de script)

Crie ou atualize Executar Comando em uma VM passando o conteúdo do script diretamente para o parâmetro -SourceScript. Use ; para separar vários comandos

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVML -RunCommandName MyRunCommand2 -Location EastUS2EUAP -SourceScript "id; echo HelloWorld"

Criar ou atualizar Executar Comando em uma VM usando SourceCommandId

Crie ou atualize Executar Comando em uma VM usando commandId preexistente. CommandIds disponíveis podem ser recuperadas usando Get-AzVMRunCommandDocument.

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVMEE -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceCommandId DisableWindowsUpdate

Criar ou atualizar Executar Comando em uma VM usando OutputBlobUri, ErrorBlobUri para transmitir saída padrão e mensagens de erro padrão para blobs de acréscimo de saída e de erro

Crie ou atualize Executar Comando em uma VM e transmitir saída padrão e mensagens de erro padrão para blobs de acréscimo de saída e de erro.

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVML -RunCommandName MyRunCommand3 -Location EastUS2EUAP -ScriptLocalPath "C:\MyScriptsDir\MyScript.ps1" -OutputBlobUri <OutPutBlobUrI> -ErrorBlobUri "ErrorBlobUri

Observação

Os blobs de saída e erro devem ser do tipo AppendBlob e suas URLs SAS devem fornecer acesso de gravação, leitura, acréscimo e criação ao blob. Um tempo de expiração de 24 horas é sugerido para a URL SAS. Se o blob de saída ou de erro não existir, um blob do tipo AppendBlob será criado. As URLs SAS podem ser geradas no portal do Azure usando as opções do blob ou o token SAS usando New-AzStorageBlobSASToken.

Criar ou atualizar Executar Comando em uma VM como um usuário diferente usando os parâmetros RunAsUser e RunAsPassword

Crie ou atualize Executar Comando em uma VM como um usuário diferente usando os parâmetros RunAsUser e RunAsPassword. Para que RunAs funcione corretamente, entre em contato com o administrador da VM e verifique se o usuário foi adicionado à VM, se o usuário tem acesso aos recursos acessados pelo Executar Comando (Diretórios, Arquivos, Rede etc.) e, no caso da VM do Windows, se o serviço 'Logon Secundário' está em execução na VM.

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVMEE -RunCommandName MyRunCommand -Location EastUS2EUAP -ScriptLocalPath "C:\MyScriptsDir\MyScript.ps1" -RunAsUser myusername -RunAsPassword mypassword

Criar ou atualizar Executar Comando em um recurso de Conjuntos de Dimensionamento de Máquinas Virtuais usando SourceScriptUri (URL SAS do blob de armazenamento)

Crie ou atualize Executar Comando em um recurso de Conjuntos de Dimensionamento de Máquinas Virtuais do Windows usando uma URL SAS de um blob de armazenamento que contém um script do PowerShell.

Set-AzVmssVMRunCommand -ResourceGroupName MyRG0 -VMScaleSetName MyVMSS -InstanceId 0 -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri>

Observação

A URL SAS deve fornecer acesso de leitura ao blob. Um tempo de expiração de 24 horas é sugerido para a URL SAS. As URLs SAS podem ser geradas no portal do Azure usando as opções do blob ou o token SAS usando New-AzStorageBlobSASToken. Se gerar o token SAS usando New-AzStorageBlobSASToken, o formato de URL SAS será: URL de blob base + "?" + o token SAS de New-AzStorageBlobSASToken.

Criar ou atualizar Executar Comando em uma instância de VM usando os parâmetros Parameter e ProtectedParameter (Parâmetros Públicos e Protegidos para script)

Use ProtectedParameter para passar quaisquer entradas confidenciais para script, como senhas, chaves etc.

$PublicParametersArray = @([Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.IRunCommandInputParameter]@{name='publicParam1';value='publicParam1value'},
>> [Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.IRunCommandInputParameter]@{name='publicParam2';value='publicParam2value'})

$ProtectedParametersArray = @([Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.IRunCommandInputParameter]@{name='secret1';value='secret1value'},
>> [Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.IRunCommandInputParameter]@{name='secret2';value='secret2value'})

Set-AzVMRunCommand -ResourceGroupName MyRG0 -VMName MyVMEE -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri> -Parameter $PublicParametersArray -ProtectedParameter $ProtectedParametersArray

Windows: Parameters e ProtectedParameters são passados para o script conforme os argumentos são passados para o script e são executados assim como – myscript.ps1 -publicParam1 publicParam1value -publicParam2 publicParam2value -secret1 secret1value -secret2 secret2value
Linux: Parâmetros Nomeados e seus valores são definidos como configuração de ambiente, que deve ser acessível dentro do script .sh. Para argumentos sem nome, passe uma cadeia de caracteres vazia para nomear a entrada. Argumentos sem nome são passados para script e executados assim – myscript.sh publicParam1value publicParam2value secret1value secret2value

Excluir o recurso RunCommand da VM

Remova o recurso RunCommand implantado anteriormente na VM. Se a execução do script ainda estiver em andamento, a execução será encerrada.

Remove-AzVMRunCommand -ResourceGroupName "myRG" -VMName "myVM" -RunCommandName "RunCommandName"

API REST

Para implantar um novo Executar Comando, execute um PUT diretamente na VM e especifique um nome exclusivo para a instância de Executar Comando.

PUT /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/virtualMachines/<vmName>/runcommands/<runCommandName>?api-version=2023-03-01

{ 
"location": "<location>", 
"properties": { 
    "source": { 
        "script": "Write-Host Hello World!", 
        "scriptUri": "<SAS URI of a storage blob with read access or public URI>",  
        "commandId": "<Id>"  
        }, 
    "parameters": [ 
        { 
            "name": "param1",
            "value": "value1" 
            }, 
        { 
            "name": "param2", 
            "value": "value2" 
            } 
        ], 
    "protectedParameters": [ 
        { 
            "name": "secret1", 
            "value": "value1" 
            }, 
        { 
            "name": "secret2", 
            "value": "value2" 
            } 
        ], 
    "runAsUser": "userName",
    "runAsPassword": "userPassword", 
    "timeoutInSeconds": 3600,
    "treatFailureAsDeploymentFailure": true,
    "outputBlobUri": "< SAS URI of a storage append blob with read, add, create, write access>", 
    "errorBlobUri": "< SAS URI of a storage append blob with read, add, create, write access >"  
    }
}

Observações

Você pode fornecer um script embutido, um URI de script ou uma ID de comando de script interno como fonte de entrada. O URI de script é o URI SAS do blob de armazenamento com acesso de leitura ou URI público.
Somente um tipo de entrada de origem tem suporte para uma execução de comando.
A partir da versão da API 2023-03-01, você pode definir a propriedade treatFailureAsDeploymentFailure como true, fazendo com que a implantação falhe quando houver uma falha no script. Se definido como false, ProvisioningState refletirá apenas se o comando de execução foi executado ou não pela plataforma de extensões. Não indicará se o script falhou em caso de falhas de script.
O Comando executar dá suporte à gravação de saída e erro em blobs de armazenamento usando parâmetros outputBlobUri e errorBlobUri, que podem ser usados para armazenar saídas de script grandes. Use o URI SAS de um blob de acréscimo de armazenamento com acesso de leitura, adição, criação e gravação. O blob deve ser do tipo AppendBlob. A gravação da saída do script ou o blob de erros falharia de outra forma. O blob será substituído se ele já existir. Ele será criado se não existir.

Listar instâncias em execução do Executar Comando em uma VM

GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/virtualMachines/<vmName>/runcommands?api-version=2023-03-01

Obter detalhes de saída para uma implantação de Executar Comando específica

GET /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/virtualMachines/<vmName>/runcommands/<runCommandName>?$expand=instanceView&api-version=2023-03-01

Excluir uma implantação de Executar Comando específica

Você também pode excluir a instância de Executar Comando.

DELETE /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/virtualMachines/<vmName>/runcommands/<runCommandName>?api-version=2023-03-01

Implantar scripts em uma sequência ordenada

Para implantar scripts sequencialmente, use um modelo de implantação especificando uma relação dependsOn entre scripts sequenciais.

{ 
    "type": "Microsoft.Compute/virtualMachines/runCommands", 
    "name": "secondRunCommand", 
    "apiVersion": "2019-12-01", 
    "location": "[parameters('location')]", 
    "dependsOn": <full resourceID of the previous other Run Command>, 
    "properties": { 
        "source": {  
            "script": "Write-Host Hello World!"  
        }, 
        "timeoutInSeconds": 60  
    }
}

Executar vários Executar Comando sequencialmente

Por padrão, se você implantar vários recursos RunCommand usando o modelo de implantação, eles serão executados simultaneamente na VM. Se você tiver uma dependência nos scripts e uma ordem de execução preferida, poderá usar a propriedade dependsOn para que eles sejam executados em sequência.

Nesse exemplo, secondRunCommand será executado após firstRunCommand.

{
   "$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
   "contentVersion":"1.0.0.0",
   "resources":[
      {
         "type":"Microsoft.Compute/virtualMachines/runCommands",
         "name":"[concat(parameters('vmName'),'/firstRunCommand')]",
         "apiVersion":"2023-03-01",
         "location":"[parameters('location')]",
         "dependsOn":[
            "[concat('Microsoft.Compute/virtualMachines/', parameters('vmName'))]"
         ],
         "properties":{
            "source":{
               "script":"Write-Host First: Hello World!"
            },
            "parameters":[
               {
                  "name":"param1",
                  "value":"value1"
               },
               {
                  "name":"param2",
                  "value":"value2"
               }
            ],
            "timeoutInSeconds":20
         }
      },
      {
         "type":"Microsoft.Compute/virtualMachines/runCommands",
         "name":"[concat(parameters('vmName'),'/secondRunCommand')]",
         "apiVersion":"2019-12-01",
         "location":"[parameters('location')]",
         "dependsOn":[
            "[concat('Microsoft.Compute/virtualMachines/', parameters('vmName'),'runcommands/firstRunCommand')]"
         ],
         "properties":{
            "source":{
               "scriptUri":"http://github.com/myscript.ps1"
            },
            "timeoutInSeconds":60
         }
      }
   ]
}

Próximas etapas

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

Compartilhar via

Executar scripts em sua VM do Windows usando Executar Comando gerenciado

Pré-requisitos

Com suporte do SO do Windows

Limitando o acesso ao recurso Executar Comando

CLI do Azure

Executar um script com a VM

Listar todos os recursos de RunCommand implantados em uma VM

Obter resultados e status da execução

Excluir o recurso RunCommand da VM

PowerShell

Executar um script com a VM

Executar um script na VM usando o parâmetro SourceScriptUri

Listar todos os recursos de RunCommand implantados em uma VM

Obter resultados e status da execução

Criar ou atualizar Executar Comando em uma VM usando SourceScriptUri (URL SAS do blob de armazenamento)

Obter um modo de exibição de instância de Executar Comando para uma VM após criar ou atualizar Executar Comando

Criar ou atualizar Executar Comando em uma VM usando ScriptLocalPath (arquivo de script local)

Criar ou atualizar Executar Comando em uma VM usando SourceScript (texto de script)

Criar ou atualizar Executar Comando em uma VM usando SourceCommandId

Criar ou atualizar Executar Comando em uma VM usando OutputBlobUri, ErrorBlobUri para transmitir saída padrão e mensagens de erro padrão para blobs de acréscimo de saída e de erro

Criar ou atualizar Executar Comando em uma VM como um usuário diferente usando os parâmetros RunAsUser e RunAsPassword

Criar ou atualizar Executar Comando em um recurso de Conjuntos de Dimensionamento de Máquinas Virtuais usando SourceScriptUri (URL SAS do blob de armazenamento)

Criar ou atualizar Executar Comando em uma instância de VM usando os parâmetros Parameter e ProtectedParameter (Parâmetros Públicos e Protegidos para script)

Excluir o recurso RunCommand da VM

API REST

Observações

Listar instâncias em execução do Executar Comando em uma VM

Obter detalhes de saída para uma implantação de Executar Comando específica

Excluir uma implantação de Executar Comando específica

Implantar scripts em uma sequência ordenada

Executar vários Executar Comando sequencialmente

Próximas etapas

Comentários

Recursos adicionais