Machine Run Commands - Create Or Update

Reference

Service:: Hybrid Compute

API Version:: 2024-03-31-preview

The operation to create or update a run command.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HybridCompute/machines/{machineName}/runCommands/{runCommandName}?api-version=2024-03-31-preview

URI Parameters

Name	In	Required	Type	Description
machineName	path	True	string	The name of the hybrid machine. Regex pattern: `[a-zA-Z0-9-_\.]+`
resourceGroupName	path	True	string	The name of the resource group. The name is case insensitive.
runCommandName	path	True	string	The name of the run command. Regex pattern: `[a-zA-Z0-9-_\.]+`
subscriptionId	path	True	string	The ID of the target subscription.
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
location	True	string	The geo-location where the resource lives
properties.asyncExecution		boolean	Optional. If set to true, provisioning will complete as soon as script starts and will not wait for script to complete.
properties.errorBlobManagedIdentity		RunCommandManagedIdentity	User-assigned managed identity that has access to errorBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged
properties.errorBlobUri		string	Specifies the Azure storage blob where script error stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer errorBlobManagedIdentity parameter.
properties.outputBlobManagedIdentity		RunCommandManagedIdentity	User-assigned managed identity that has access to outputBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged
properties.outputBlobUri		string	Specifies the Azure storage blob where script output stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer outputBlobManagedIdentity parameter.
properties.parameters		RunCommandInputParameter[]	The parameters used by the script.
properties.protectedParameters		RunCommandInputParameter[]	The parameters used by the script.
properties.runAsPassword		string	Specifies the user account password on the machine when executing the run command.
properties.runAsUser		string	Specifies the user account on the machine when executing the run command.
properties.source		MachineRunCommandScriptSource	The source of the run command script.
properties.timeoutInSeconds		integer	The timeout in seconds to execute the run command.
tags		object	Resource tags.

Responses

Name	Type	Description
200 OK	MachineRunCommand	Updated Resource
201 Created	MachineRunCommand	Created Headers Location: string Retry-After: integer Azure-AsyncOperation: string
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Name

Type

Description

200 OK

MachineRunCommand

Updated Resource

201 Created

MachineRunCommand

Created

Headers

Location: string
Retry-After: integer
Azure-AsyncOperation: string

Other Status Codes

ErrorResponse

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Create or Update a Run Command

Sample Request

HTTP

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.HybridCompute/machines/myMachine/runCommands/myRunCommand?api-version=2024-03-31-preview

{
  "location": "eastus2",
  "properties": {
    "source": {
      "script": "Write-Host Hello World!"
    },
    "parameters": [
      {
        "name": "param1",
        "value": "value1"
      },
      {
        "name": "param2",
        "value": "value2"
      }
    ],
    "asyncExecution": false,
    "runAsUser": "user1",
    "runAsPassword": "<runAsPassword>",
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt"
  }
}

Sample Response

Status code:: 200

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.HybridCompute/Machines/myMachine/runcommands/myRunCommand",
  "name": "myRunCommand",
  "type": "Microsoft.HybridCompute/machines/runcommands",
  "location": "eastus2",
  "properties": {
    "source": {
      "script": "Write-Host Hello World!"
    },
    "parameters": [
      {
        "name": "param1",
        "value": "value1"
      },
      {
        "name": "param2",
        "value": "value2"
      }
    ],
    "asyncExecution": false,
    "runAsUser": "user1",
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt",
    "provisioningState": "Succeeded"
  }
}

Status code:: 201

Location: {callbackUrl}
Retry-After: 200
Azure-AsyncOperation: {callbackUri}

Response Body

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.HybridCompute/Machines/myMachine/runcommands/myRunCommand",
  "name": "myRunCommand",
  "type": "Microsoft.HybridCompute/machines/runcommands",
  "location": "eastus2",
  "properties": {
    "source": {
      "script": "Write-Host Hello World!"
    },
    "parameters": [
      {
        "name": "param1",
        "value": "value1"
      },
      {
        "name": "param2",
        "value": "value2"
      }
    ],
    "asyncExecution": false,
    "runAsUser": "user1",
    "timeoutInSeconds": 3600,
    "outputBlobUri": "https://mystorageaccount.blob.core.windows.net/myscriptoutputcontainer/MyScriptoutput.txt",
    "errorBlobUri": "https://mystorageaccount.blob.core.windows.net/mycontainer/MyScriptError.txt",
    "provisioningState": "Creating"
  }
}

Definitions

Name	Description
createdByType	The type of identity that created the resource.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
ExecutionState	Script execution status.
ExtensionsResourceStatus	Instance view status.
ExtensionsStatusLevelTypes	The level code.
MachineRunCommand	Describes a Run Command
MachineRunCommandInstanceView	The instance view of a machine run command.
MachineRunCommandScriptSource	Describes the script sources for run command. Use only one of script, scriptUri, commandId.
RunCommandInputParameter	Describes the properties of a run command parameter.
RunCommandManagedIdentity	Contains clientId or objectId (use only one, not both) of a user-assigned managed identity that has access to storage blob used in Run Command. Use an empty RunCommandManagedIdentity object in case of system-assigned identity. Make sure the Azure storage blob exists in case of scriptUri, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment with scriptUri blob and 'Storage Blob Data Contributor' for Append blobs(outputBlobUri, errorBlobUri). In case of user assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.
systemData	Metadata pertaining to creation and last modification of the resource.

createdByType

The type of identity that created the resource.

Name	Type	Description
Application	string
Key	string
ManagedIdentity	string
User	string

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Error response

Name	Type	Description
error	ErrorDetail	The error object.

ExecutionState

Script execution status.

Name	Type	Description
Canceled	string
Failed	string
Pending	string
Running	string
Succeeded	string
TimedOut	string
Unknown	string

ExtensionsResourceStatus

Instance view status.

Name	Type	Description
code	string	The status code.
displayStatus	string	The short localizable label for the status.
level	ExtensionsStatusLevelTypes	The level code.
message	string	The detailed status message, including for alerts and error messages.
time	string	The time of the status.

ExtensionsStatusLevelTypes

The level code.

Name	Type	Description
Error	string
Info	string
Warning	string

MachineRunCommand

Describes a Run Command

Name	Type	Default Value	Description
id	string		Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
location	string		The geo-location where the resource lives
name	string		The name of the resource
properties.asyncExecution	boolean	False	Optional. If set to true, provisioning will complete as soon as script starts and will not wait for script to complete.
properties.errorBlobManagedIdentity	RunCommandManagedIdentity		User-assigned managed identity that has access to errorBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged
properties.errorBlobUri	string		Specifies the Azure storage blob where script error stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer errorBlobManagedIdentity parameter.
properties.instanceView	MachineRunCommandInstanceView		The machine run command instance view.
properties.outputBlobManagedIdentity	RunCommandManagedIdentity		User-assigned managed identity that has access to outputBlobUri storage blob. Use an empty object in case of system-assigned identity. Make sure managed identity has been given access to blob's container with 'Storage Blob Data Contributor' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged
properties.outputBlobUri	string		Specifies the Azure storage blob where script output stream will be uploaded. Use a SAS URI with read, append, create, write access OR use managed identity to provide the VM access to the blob. Refer outputBlobManagedIdentity parameter.
properties.parameters	RunCommandInputParameter[]		The parameters used by the script.
properties.protectedParameters	RunCommandInputParameter[]		The parameters used by the script.
properties.provisioningState	string		The provisioning state, which only appears in the response.
properties.runAsPassword	string		Specifies the user account password on the machine when executing the run command.
properties.runAsUser	string		Specifies the user account on the machine when executing the run command.
properties.source	MachineRunCommandScriptSource		The source of the run command script.
properties.timeoutInSeconds	integer		The timeout in seconds to execute the run command.
systemData	systemData		Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags	object		Resource tags.
type	string		The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

MachineRunCommandInstanceView

The instance view of a machine run command.

Name	Type	Description
endTime	string	Script end time.
error	string	Script error stream.
executionMessage	string	Communicate script configuration errors or execution messages.
executionState	ExecutionState	Script execution status.
exitCode	integer	Exit code returned from script execution.
output	string	Script output stream.
startTime	string	Script start time.
statuses	ExtensionsResourceStatus[]	The status information.

MachineRunCommandScriptSource

Describes the script sources for run command. Use only one of script, scriptUri, commandId.

Name	Type	Description
commandId	string	Specifies the commandId of predefined built-in script.
script	string	Specifies the script content to be executed on the machine.
scriptUri	string	Specifies the script download location. It can be either SAS URI of an Azure storage blob with read access or public URI.
scriptUriManagedIdentity	RunCommandManagedIdentity	User-assigned managed identity that has access to scriptUri in case of Azure storage blob. Use an empty object in case of system-assigned identity. Make sure the Azure storage blob exists, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment. In case of user-assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.

RunCommandInputParameter

Describes the properties of a run command parameter.

Name	Type	Description
name	string	The run command parameter name.
value	string	The run command parameter value.

RunCommandManagedIdentity

Contains clientId or objectId (use only one, not both) of a user-assigned managed identity that has access to storage blob used in Run Command. Use an empty RunCommandManagedIdentity object in case of system-assigned identity. Make sure the Azure storage blob exists in case of scriptUri, and managed identity has been given access to blob's container with 'Storage Blob Data Reader' role assignment with scriptUri blob and 'Storage Blob Data Contributor' for Append blobs(outputBlobUri, errorBlobUri). In case of user assigned identity, make sure you add it under VM's identity. For more info on managed identity and Run Command, refer https://aka.ms/ManagedIdentity and https://aka.ms/RunCommandManaged.

Name	Type	Description
clientId	string	Client Id (GUID value) of the user-assigned managed identity. ObjectId should not be used if this is provided.
objectId	string	Object Id (GUID value) of the user-assigned managed identity. ClientId should not be used if this is provided.

systemData

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

Share via

Machine Run Commands - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Create or Update a Run Command

Sample Request

Sample Response

Definitions

createdByType

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

ExecutionState

ExtensionsResourceStatus

ExtensionsStatusLevelTypes

MachineRunCommand

MachineRunCommandInstanceView

MachineRunCommandScriptSource

RunCommandInputParameter

RunCommandManagedIdentity

systemData

Additional resources