使用受控執行命令在 Windows VM 中執行指令碼

發行項
03/12/2024

適用於：✔️ Windows VM ✔️ 彈性擴展集

重要

受控執行命令 目前可在 Azure CLI、PowerShell 和 API 中使用。入口網站功能即將推出。

執行命令功能會使用虛擬機（VM）代理程式在 Azure Windows VM 內執行腳本。您可以使用這些指令碼，進行一般電腦或應用程式管理。其可協助您快速診斷和補救 VM 存取和網路問題，並讓 VM 回到良好的狀態。

更新的受控執行命令會使用相同的 VM 代理程式通道來執行腳本，並提供下列針對原始動作導向執行命令的增強功能：

支援透過ARM部署範本更新的執行命令
平行執行多個指令碼
循序執行指令碼
使用者指定的腳本逾時
長時間執行（小時/天）文本的支援
以安全的方式傳遞秘密 (參數、密碼)

必要條件

Windows OS 支援

Windows OS	x64
Windows 10	支援
Windows 11	支援
Windows Server 2008 SP2	支援
Windows Server 2008 R2	支援
Windows Server 2012	支援
Windows Server 2012 R2	支援
Windows Server 2016	支援
Windows Server 2016 Core	支援
Windows Server 2019	支援
Windows Server 2019 Core	支援
Windows Server 2022	支援
Windows Server 2022 Core	支援

限制於執行命令的存取

列出執行命令，或顯示命令的詳細數據需要 Microsoft.Compute/locations/runCommands/read 訂用帳戶層級的許可權。內建讀者角色和具有此權限的較高層級。

執行命令需要有 Microsoft.Compute/virtualMachines/runCommand/write 權限。虛擬機器參與者角色和具有此權限的較高層級。

您可使用其中一個內建角色或建立自訂角色，以使用 [執行] 命令。

Azure CLI

下列範例使用 az vm run-command 在 Azure Windows VM 上執行殼層腳本。

使用 VM 執行腳本

此命令會將腳本傳遞至 VM、執行它，並傳回擷取的輸出。

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

列出 VM 上所有已部署的 RunCommand 資源

此命令會傳回先前部署的執行命令及其屬性的完整清單。

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

取得執行狀態和結果

此命令會擷取目前的執行進度，包括最新的輸出、開始/結束時間、結束代碼，以及執行的終端機狀態。

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

注意

中的 instanceView 輸出和錯誤欄位限制為最後 4KB。如果您想要存取完整的輸出和錯誤，您可以選擇在使用或 Set-AzVMssRunCommand執行命令Set-AzVMRunCommand時，使用 -outputBlobUri 和 -errorBlobUri 參數將輸出和錯誤資料轉送至記憶體附加 Blob。

從 VM 刪除 RunCommand 資源

拿掉先前部署在 VM 上的 RunCommand 資源。如果腳本執行仍在進行中，則會終止執行。

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

PowerShell

使用 VM 執行腳本

此命令會將腳本傳遞至 VM、執行它，並傳回擷取的輸出。

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

使用 SourceScriptUri 參數在 VM 上執行腳本

OutputBlobUri 和 ErrorBlobUri 是選擇性參數。

Set-AzVMRunCommand -ResourceGroupName -VMName -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>”

列出 VM 上所有已部署的 RunCommand 資源

此命令會傳回先前部署的執行命令及其屬性的完整清單。

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

取得執行狀態和結果

此命令會擷取目前的執行進度，包括最新的輸出、開始/結束時間、結束代碼，以及執行的終端機狀態。

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

使用 SourceScriptUri 在 VM 上建立或更新執行命令（記憶體 Blob SAS URL）

使用包含 PowerShell 腳本之記憶體 Blob 的 SAS URL，在 Windows VM 上建立或更新執行命令。 SourceScriptUri 可以是記憶體 Blob 的完整 SAS URL 或公用 URL。

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

注意

SAS URL 必須提供 Blob 的讀取許可權。 SAS URL 建議到期時間為24小時。您可以使用 Blob 的選項，或使用的 SAS 令牌New-AzStorageBlobSASToken，在 Azure 入口網站產生 SAS URL。如果使用產生 SAS 令牌 New-AzStorageBlobSASToken，則您的 SAS URL = “base blob URL” + “？” + “SAS Token from New-AzStorageBlobSASToken”

建立或更新執行命令之後，取得 VM 的執行命令實例檢視

取得具有實例檢視的 VM 執行命令。實例檢視包含執行命令的執行狀態（成功、失敗等）、結束碼、標準輸出，以及使用執行命令執行腳本所產生的標準錯誤。非零的 ExitCode 表示執行失敗。

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

範例輸出

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：使用者執行命令文本的狀態。請參閱此狀態，以瞭解您的腳本是否成功。 ProvisioningState：一般延伸模組布建端對端的狀態（延伸模組平臺是否能夠觸發執行命令腳本）。

使用 ScriptLocalPath 在 VM 上建立或更新執行命令（本機腳本檔案）

使用執行 Cmdlet 之用戶端電腦上的本機腳本檔案，在 VM 上建立或更新執行命令。

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

使用 SourceScript 在 VM 上建立或更新執行命令（文稿文字）

在將腳本內容直接傳遞至 -SourceScript 參數的 VM 上建立或更新執行命令。用來 ; 分隔多個命令

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

使用 SourceCommandId 在 VM 上建立或更新執行命令

使用既有的 commandId 在 VM 上建立或更新執行命令。您可以使用 Get-AzVMRunCommandDocument 來擷取可用的 commandId。

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

使用 OutputBlobUri、ErrorBlobUri 在 VM 上建立或更新執行命令，以將標準輸出和標準錯誤訊息串流至輸出和錯誤附加 Blob

在 VM 上建立或更新執行命令，並將標準輸出和標準錯誤訊息串流至輸出和錯誤附加 Blob。

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

注意

輸出和錯誤 Blob 必須是 AppendBlob 類型，且其 SAS URL 必須提供 Blob 的讀取、附加、建立、寫入許可權。 SAS URL 建議到期時間為24小時。如果輸出或錯誤 Blob 不存在，則會建立 AppendBlob 類型的 Blob。您可以使用 Blob 的選項，或使用 New-AzStorageBlobSASToken的 SAS 令牌，在 Azure 入口網站產生 SAS URL。

使用 RunAsUser 和 RunAsPassword 參數，以不同使用者身分在 VM 上建立或更新執行命令

使用 RunAsUser 和 RunAsPassword 參數，以不同的使用者身分在 VM 上建立或更新執行命令。若要讓 RunAs 正常運作，請連絡 VM 的管理員，並確定已在 VM 上新增使用者、使用者有權存取執行命令存取的資源（目錄、檔案、網路等），並在 Windows VM 上執行「次要登入」服務。

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

使用 SourceScriptUri 在虛擬機器擴展集資源上建立或更新執行命令（記憶體 Blob SAS URL）

使用包含 PowerShell 腳本之記憶體 Blob 的 SAS URL，在 Windows 虛擬機器擴展集資源上建立或更新執行命令。

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

注意

SAS URL 必須提供 Blob 的讀取許可權。 SAS URL 建議到期時間為24小時。您可以使用 Blob 的選項，或使用的 SAS 令牌New-AzStorageBlobSASToken，在 Azure 入口網站上產生 SAS URL。如果使用產生 SAS 令牌 New-AzStorageBlobSASToken，則 SAS URL 格式為：基底 Blob URL + “？” + 來自 New-AzStorageBlobSASToken的 SAS 令牌。

使用 Parameter 和 ProtectedParameter 參數在 VM 實例上建立或更新執行命令（要編寫腳本的公用和受保護的參數）

使用 ProtectedParameter 將任何敏感性輸入傳遞至腳本，例如密碼、密鑰等。

$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：參數和 ProtectedParameters 會傳遞至腳本，因為自變數會傳遞至腳本並像這樣執行 - myscript.ps1 -publicParam1 publicParam1value -publicParam2 publicParam2value -secret1 secret1value -secret2 secret2value
Linux：具名參數及其值會設定為環境組態，這應該可在.sh腳本中存取。針對無名稱自變數，將空字串傳遞至名稱輸入。無名稱自變數會傳遞至文稿並像這樣執行 - myscript.sh publicParam1value publicParam2value secret1value secret2value

從 VM 刪除 RunCommand 資源

拿掉先前部署在 VM 上的 RunCommand 資源。如果腳本執行仍在進行中，則會終止執行。

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

REST API

若要部署新的執行命令，請直接在 VM 上執行 PUT，並指定執行命令實例的唯一名稱。

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 >"  
    }
}

備註

您可以提供內嵌文稿、腳本 URI 或內建腳本命令識別碼作為輸入來源。腳本 URI 是具有讀取許可權或公用 URI 的記憶體 Blob SAS URI。
單一命令執行只支援一種類型的來源輸入。
從 API 2023-03-01 版開始，您可以將屬性 treatFailureAsDeploymentFailure 設定為 true ，導致腳本失敗時部署失敗。如果設定為 false，ProvisioningState 只會反映延伸模組平臺是否執行 run 命令。它不會指出文稿在文稿失敗時是否失敗。
執行命令支援使用 outputBlobUri 和 errorBlobUri 參數將輸出和錯誤寫入至儲存體 Blob，可用來儲存大型腳本輸出。使用記憶體附加 Blob 的 SAS URI 搭配讀取、新增、建立、寫入存取。 Blob 的類型應該是 AppendBlob。寫入文本輸出或錯誤 Blob 會失敗，否則會失敗。如果 Blob 已經存在，則會覆寫 Blob。如果不存在，則會建立它。

列出 VM 上執行命令的執行實例

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

取得特定執行命令部署的輸出詳細數據

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

刪除特定的執行命令部署

您也可以刪除執行命令的實體。

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

以排序順序部署腳本

若要循序部署文本，請使用部署範本，指定 dependsOn 循序腳本之間的關聯性。

{ 
    "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  
    }
}

循序執行多個執行命令

根據預設，如果您使用部署範本部署多個 RunCommand 資源，則會在 VM 上同時執行它們。如果您相依於文稿和慣用的執行順序，您可以使用 dependsOn 屬性來讓它們循序執行。

在此範例中，secondRunCommand 會在 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
         }
      }
   ]
}

下一步

若要瞭解在 VM 中遠端執行文本和命令的其他方式，請參閱在 Windows VM 中執行腳本。

Share via

使用受控執行命令在 Windows VM 中執行指令碼

必要條件

Windows OS 支援

限制於執行命令的存取

Azure CLI

使用 VM 執行腳本

列出 VM 上所有已部署的 RunCommand 資源

取得執行狀態和結果

從 VM 刪除 RunCommand 資源

PowerShell

使用 VM 執行腳本

使用 SourceScriptUri 參數在 VM 上執行腳本

列出 VM 上所有已部署的 RunCommand 資源

取得執行狀態和結果

使用 SourceScriptUri 在 VM 上建立或更新執行命令（記憶體 Blob SAS URL）

建立或更新執行命令之後，取得 VM 的執行命令實例檢視

使用 ScriptLocalPath 在 VM 上建立或更新執行命令（本機腳本檔案）

使用 SourceScript 在 VM 上建立或更新執行命令（文稿文字）

使用 SourceCommandId 在 VM 上建立或更新執行命令

使用 OutputBlobUri、ErrorBlobUri 在 VM 上建立或更新執行命令，以將標準輸出和標準錯誤訊息串流至輸出和錯誤附加 Blob

使用 RunAsUser 和 RunAsPassword 參數，以不同使用者身分在 VM 上建立或更新執行命令

使用 SourceScriptUri 在虛擬機器擴展集資源上建立或更新執行命令（記憶體 Blob SAS URL）

使用 Parameter 和 ProtectedParameter 參數在 VM 實例上建立或更新執行命令（要編寫腳本的公用和受保護的參數）

從 VM 刪除 RunCommand 資源

REST API

備註

列出 VM 上執行命令的執行實例

取得特定執行命令部署的輸出詳細數據

刪除特定的執行命令部署

以排序順序部署腳本

循序執行多個執行命令

下一步

其他資源

Share via

使用受控執行命令在 Windows VM 中執行指令碼

必要條件

Windows OS 支援

限制於執行命令的存取

Azure CLI

使用 VM 執行腳本

列出 VM 上所有已部署的 RunCommand 資源

取得執行狀態和結果

從 VM 刪除 RunCommand 資源

PowerShell

使用 VM 執行腳本

使用 SourceScriptUri 參數在 VM 上執行腳本

列出 VM 上所有已部署的 RunCommand 資源

取得執行狀態和結果

使用 SourceScriptUri 在 VM 上建立或更新執行命令 （記憶體 Blob SAS URL）

建立或更新執行命令之後，取得 VM 的執行命令實例檢視

使用 ScriptLocalPath 在 VM 上建立或更新執行命令 （本機腳本檔案）

使用 SourceScript 在 VM 上建立或更新執行命令 （文稿文字）

使用 SourceCommandId 在 VM 上建立或更新執行命令

使用 OutputBlobUri、ErrorBlobUri 在 VM 上建立或更新執行命令，以將標準輸出和標準錯誤訊息串流至輸出和錯誤附加 Blob

使用 RunAsUser 和 RunAsPassword 參數，以不同使用者身分在 VM 上建立或更新執行命令

使用 SourceScriptUri 在 虛擬機器擴展集 資源上建立或更新執行命令（記憶體 Blob SAS URL）

使用 Parameter 和 ProtectedParameter 參數在 VM 實例上建立或更新執行命令（要編寫腳本的公用和受保護的參數）

從 VM 刪除 RunCommand 資源

REST API

備註

列出 VM 上執行命令的執行實例

取得特定執行命令部署的輸出詳細數據

刪除特定的執行命令部署

以排序順序部署腳本

循序執行多個執行命令

下一步

其他資源

使用 SourceScriptUri 在 VM 上建立或更新執行命令（記憶體 Blob SAS URL）

使用 ScriptLocalPath 在 VM 上建立或更新執行命令（本機腳本檔案）

使用 SourceScript 在 VM 上建立或更新執行命令（文稿文字）

使用 SourceScriptUri 在虛擬機器擴展集資源上建立或更新執行命令（記憶體 Blob SAS URL）