マネージド実行コマンドを使用して Windows VM でスクリプトを実行する

適用対象: ✔️ Windows VM ✔️ フレキシブル スケール セット

実行コマンド機能では、仮想マシン (VM) エージェントを使用して Azure Windows VM 内でスクリプトが実行されます。 これらのスクリプトは、マシンやアプリケーションの一般的な管理に使用できます。 これらを使用すれば、VM のアクセスおよびネットワークの問題を迅速に診断して修正し、VM を良好な状態に戻すことができます。

更新されたマネージド実行コマンドでは、同じ VM エージェント チャネルを使用してスクリプトを実行し、元のアクション指向実行コマンドに対して次の機能強化を実現します。

• ARM デプロイ テンプレートを介して更新された実行コマンドをサポート
• 複数のスクリプトの並列実行
• スクリプトの順次実行
• ユーザーが指定したスクリプトのタイムアウト
• 実行時間が長い (時間または日単位) のスクリプトをサポート
• 安全な方法でシークレット (パラメーター、パスワード) を渡す

前提条件

サポートされている Windows オペレーティング システム

使用可能なコマンド

実行コマンドへのアクセスの制限

実行コマンドを一覧表示したり、コマンドの詳細を表示したりするには、サブスクリプション レベルの 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

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

VM で長期の実行コマンドを実行する

実行時間は、既定のタイムアウトである 90 分より長く続くことがあります。 スクリプトの実行時間が長いと予想される場合は、実行が 100 分間におよぶことがあります (6,0000-seconds -TimeoutInSecond パラメーターのため)。 100 分経過すると、スクリプトの実行が停止します。

Set-AzVMRunCommand -ResourceGroupName MyRG -VMName MyVM -RunCommandName MyRunCommand -Location EastUS2EUAP -SourceScriptUri <SourceScriptUri> -AsyncExecution -TimeoutInSecond 6000

VM 上にデプロイされているすべての RunCommand リソースを一覧表示する

このコマンドからは、以前にデプロイされた実行コマンドと、それらのプロパティの完全な一覧が返されます。

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

実行の状態と結果を取得する

このコマンドは、現在の実行の進行状況 (最新の出力、開始/終了時刻、終了コード、実行の終了状態など) を取得します。

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

SourceScriptUri (ストレージ BLOB SAS URL) を使用して VM で実行コマンドを作成または更新する

PowerShell スクリプトを含むストレージ BLOB の SAS URL を使用して、Windows VM で実行コマンドを作成または更新します。 SourceScriptUri には、ストレージ BLOB の完全な SAS URL またはパブリック URL を指定できます。

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

実行コマンドの作成または更新後に VM の実行コマンド インスタンス ビューを取得する

インスタンス ビューを使用して VM の実行コマンドを取得します。 インスタンス ビューには、実行コマンド (成功、失敗など)、終了コード、標準出力、実行コマンドを使用してスクリプトを実行して生成された標準エラーの実行状態が含まれています。 0 以外の 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 で実行コマンドを作成または更新する

コマンドレットが実行されるクライアント コンピューター上にあるローカル スクリプト ファイルを使用して、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 で Run Command を作成または更新します。 使用可能な commandId は、Get-AzVMRunCommandDocument を使用して取得できます。

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

RunAsUser および RunAsPassword パラメーターを使用して別のユーザーとして VM で実行コマンドを作成または更新する

RunAsUser および RunAsPassword パラメーターを使用して、別のユーザーとして VM で実行コマンドを作成または更新します。 RunAs が正常に機能させるには、VM の管理者に問い合わせて、VM にユーザーが追加されていること、ユーザーが実行コマンドによってアクセスされるリソース (ディレクトリ、ファイル、ネットワークなど) にアクセスできること、また、Windows VM の場合は、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 Virtual Machine Scale Sets リソースで実行コマンドを作成または更新します。

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

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: Parameter と ProtectedParameter は引数としてスクリプトに渡され、次のように実行されます: myscript.ps1 -publicParam1 publicParam1value -publicParam2 publicParam2value -secret1 secret1value -secret2 secret2value

• Linux: 名前付きパラメーターとその値は、.sh スクリプト内でアクセスできる環境構成に設定されます。 Nameless 引数の場合は、空の文字列を name 入力に渡します。 Nameless 引数はスクリプトに渡され、次のように実行されます 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、または組み込みのスクリプト コマンド ID を指定できます。 スクリプト URI は、読み取りアクセス権を持つストレージ BLOB SAS URI またはパブリック URI のいずれかです。
• 1 回のコマンド実行でサポートされるソース入力は 1 種類だけです。
• API バージョン 2023-03-01 以降では、 プロパティ treatFailureAsDeploymentFailure を true に設定することで、スクリプトにエラーが発生したときにデプロイが失敗させることができます。 false に設定すると、ProvisioningState は、実行コマンドが拡張機能プラットフォームによって実行されたかどうかのみを反映します。 スクリプトが失敗した場合、スクリプトが失敗したかどうかは示されません。
• 実行コマンドでは、outputBlobUri パラメーターと errorBlobUri パラメーターを使用したストレージ BLOB への出力とエラーの書き込みがサポートされています。これは、大きなスクリプト出力の格納に使用できます。 読み取り、追加、作成、書き込みアクセス権を持つストレージ追加 BLOB の SAS URI を使用します。 BLOB は AppendBlob 型である必要があります。 そうでない場合、スクリプト出力またはエラー 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 プロパティを使用してそれらを順番に実行することができます。

この例では、firstRunCommand が実行されてから、secondRunCommand が実行されます。

{
   "$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 でスクリプトを実行する」を参照してください。