Microsoft Azure VirtualMachineRunCommands API

openapi: 3.2.0
info:
  title: Microsoft Azure RunCommandsClient Virtual Machine Run…
  description: The Run Commands Client.
  version: '2024-03-01'
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: VirtualMachineRunCommands
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/{location}/runCommands:
    get:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsList
      x-ms-examples:
        VirtualMachineRunCommandList:
          $ref: ./examples/runCommandExamples/RunCommand_List.json
      description: Lists all available run commands for a subscription in a location.
      parameters:
      - name: location
        in: path
        required: true
        description: The location upon which run commands is queried.
        schema:
          type: string
          pattern: ^[-\w\._]+$
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunCommandListResult'
            text/json:
              schema:
                $ref: '#/components/schemas/RunCommandListResult'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Subscriptions Subscriptionid Providers Microsoft Compute…
  /subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/{location}/runCommands/{commandId}:
    get:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsGet
      x-ms-examples:
        VirtualMachineRunCommandGet:
          $ref: ./examples/runCommandExamples/RunCommand_Get.json
      description: Gets specific run command for a subscription in a location.
      parameters:
      - name: location
        in: path
        required: true
        description: The location upon which run commands is queried.
        schema:
          type: string
          pattern: ^[-\w\._]+$
      - name: commandId
        in: path
        required: true
        description: The command id.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunCommandDocument'
            text/json:
              schema:
                $ref: '#/components/schemas/RunCommandDocument'
      summary: Microsoft Azure Get Subscriptions Subscriptionid Providers Microsoft Compute…
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommands/{runCommandName}
  : put:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsCreateorupdate
      description: The operation to create or update the run command.
      parameters:
      - name: resourceGroupName
        in: path
        required: true
        description: The name of the resource group.
        schema:
          type: string
      - name: vmName
        in: path
        required: true
        description: The name of the virtual machine where the run command should be created or updated.
        schema:
          type: string
      - name: runCommandName
        in: path
        required: true
        description: The name of the virtual machine run command.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
            text/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
            text/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
            text/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
      x-ms-long-running-operation: true
      x-ms-examples:
        Create or update a run command.:
          $ref: ./examples/runCommandExamples/VirtualMachineRunCommand_CreateOrUpdate.json
      summary: Microsoft Azure Put Subscriptions Subscriptionid Resourcegroups…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualMachineRunCommand'
          text/json:
            schema:
              $ref: '#/components/schemas/VirtualMachineRunCommand'
        description: Parameters supplied to the Create Virtual Machine RunCommand operation.
        required: true
    patch:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsUpdate
      description: The operation to update the run command.
      parameters:
      - name: resourceGroupName
        in: path
        required: true
        description: The name of the resource group.
        schema:
          type: string
      - name: vmName
        in: path
        required: true
        description: The name of the virtual machine where the run command should be updated.
        schema:
          type: string
      - name: runCommandName
        in: path
        required: true
        description: The name of the virtual machine run command.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
            text/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
            text/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
      x-ms-long-running-operation: true
      x-ms-examples:
        Update a run command.:
          $ref: ./examples/runCommandExamples/VirtualMachineRunCommand_Update.json
      summary: Microsoft Azure Patch Subscriptions Subscriptionid Resourcegroups…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualMachineRunCommandUpdate'
          text/json:
            schema:
              $ref: '#/components/schemas/VirtualMachineRunCommandUpdate'
        description: Parameters supplied to the Update Virtual Machine RunCommand operation.
        required: true
    delete:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsDelete
      description: The operation to delete the run command.
      parameters:
      - name: resourceGroupName
        in: path
        required: true
        description: The name of the resource group.
        schema:
          type: string
      - name: vmName
        in: path
        required: true
        description: The name of the virtual machine where the run command should be deleted.
        schema:
          type: string
      - name: runCommandName
        in: path
        required: true
        description: The name of the virtual machine run command.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
        '202':
          description: Accepted
        '204':
          description: No Content
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
            text/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
      x-ms-long-running-operation: true
      x-ms-examples:
        Delete a run command.:
          $ref: ./examples/runCommandExamples/VirtualMachineRunCommand_Delete.json
      summary: Microsoft Azure Delete Subscriptions Subscriptionid Resourcegroups…
    get:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsGetbyvirtualmachine
      description: The operation to get the run command.
      parameters:
      - name: resourceGroupName
        in: path
        required: true
        description: The name of the resource group.
        schema:
          type: string
      - name: vmName
        in: path
        required: true
        description: The name of the virtual machine containing the run command.
        schema:
          type: string
      - name: runCommandName
        in: path
        required: true
        description: The name of the virtual machine run command.
        schema:
          type: string
      - name: $expand
        in: query
        required: false
        description: The expand expression to apply on the operation.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
            text/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommand'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
            text/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
      x-ms-examples:
        Get a run command.:
          $ref: ./examples/runCommandExamples/VirtualMachineRunCommand_Get.json
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups…
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/runCommands
  : get:
      tags:
      - VirtualMachineRunCommands
      operationId: microsoftAzureVirtualmachineruncommandsListbyvirtualmachine
      description: The operation to get all run commands of a Virtual Machine.
      parameters:
      - name: resourceGroupName
        in: path
        required: true
        description: The name of the resource group.
        schema:
          type: string
      - name: vmName
        in: path
        required: true
        description: The name of the virtual machine containing the run command.
        schema:
          type: string
      - name: $expand
        in: query
        required: false
        description: The expand expression to apply on the operation.
        schema:
          type: string
      - $ref: ../../../common-types/v1/common.json#/parameters/ApiVersionParameter
      - $ref: ../../../common-types/v1/common.json#/parameters/SubscriptionIdParameter
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommandsListResult'
            text/json:
              schema:
                $ref: '#/components/schemas/VirtualMachineRunCommandsListResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
            text/json:
              schema:
                $ref: ../../../common-types/v1/common.json#/definitions/CloudError
      x-ms-examples:
        List run commands in a Virtual Machine.:
          $ref: ./examples/runCommandExamples/VirtualMachineRunCommand_List.json
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups…
components:
  schemas:
    RunCommandInputParameter:
      properties:
        name:
          type: string
          description: The run command parameter name.
        value:
          type: string
          description: The run command parameter value.
      required:
      - name
      - value
      type: object
      description: Describes the properties of a run command parameter.
    VirtualMachineRunCommand:
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/VirtualMachineRunCommandProperties'
      allOf:
      - $ref: ../../../common-types/v1/common.json#/definitions/Resource
      type: object
      description: Describes a Virtual Machine run command.
    RunCommandManagedIdentity:
      properties:
        clientId:
          type: string
          description: Client Id (GUID value) of the user-assigned managed identity. ObjectId should not be used if this is provided.
        objectId:
          type: string
          description: Object Id (GUID value) of the user-assigned managed identity. ClientId should not be used if this is provided.
      type: object
      description: ' 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.'
    VirtualMachineRunCommandScriptSource:
      properties:
        script:
          type: string
          description: Specifies the script content to be executed on the VM.
        scriptUri:
          type: string
          description: Specifies the script download location. It can be either SAS URI of an Azure storage blob with read access or public URI.
        commandId:
          type: string
          description: Specifies a commandId of predefined built-in script.
        scriptUriManagedIdentity:
          $ref: '#/components/schemas/RunCommandManagedIdentity'
          description: 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.
      type: object
      description: Describes the script sources for run command. Use only one of script, scriptUri, commandId.
    RunCommandListResult:
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/RunCommandDocumentBase'
          description: The list of virtual machine run commands.
        nextLink:
          type: string
          description: The uri to fetch the next page of run commands. Call ListNext() with this to fetch the next page of run commands.
      required:
      - value
      type: object
      description: The List Virtual Machine operation response.
    RunCommandDocument:
      allOf:
      - $ref: '#/components/schemas/RunCommandDocumentBase'
      properties:
        script:
          type: array
          items:
            type: string
          description: The script to be executed.
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/RunCommandParameterDefinition'
          x-ms-identifiers:
          - name
          - type
          description: The parameters used by the script.
      required:
      - script
      type: object
      description: Describes the properties of a Run Command.
    VirtualMachineRunCommandUpdate:
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/VirtualMachineRunCommandProperties'
      allOf:
      - $ref: ./computeRPCommon.json#/definitions/UpdateResource
      type: object
      description: Describes a Virtual Machine run command.
    VirtualMachineRunCommandProperties:
      properties:
        source:
          $ref: '#/components/schemas/VirtualMachineRunCommandScriptSource'
          description: The source of the run command script.
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/RunCommandInputParameter'
          x-ms-identifiers:
          - name
          description: The parameters used by the script.
        protectedParameters:
          type: array
          items:
            $ref: '#/components/schemas/RunCommandInputParameter'
          x-ms-identifiers:
          - name
          description: The parameters used by the script.
        asyncExecution:
          type: boolean
          description: Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.
          default: false
        runAsUser:
          type: string
          description: Specifies the user account on the VM when executing the run command.
        runAsPassword:
          type: string
          description: Specifies the user account password on the VM when executing the run command.
        timeoutInSeconds:
          type: integer
          format: int32
          description: The timeout in seconds to execute the run command.
        outputBlobUri:
          type: string
          description: '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. '
        errorBlobUri:
          type: string
          description: 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.
        outputBlobManagedIdentity:
          $ref: '#/components/schemas/RunCommandManagedIdentity'
          description: '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 '
        errorBlobManagedIdentity:
          $ref: '#/components/schemas/RunCommandManagedIdentity'
          description: '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 '
        provisioningState:
          readOnly: true
          type: string
          description: 'The provisioning state, which only appears in the response. If treatFailureAsDeploymentFailure set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If treatFailureAsDeploymentFailure set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results '
        instanceView:
          readOnly: true
          $ref: '#/components/schemas/VirtualMachineRunCommandInstanceView'
          description: The virtual machine run command instance view.
        treatFailureAsDeploymentFailure:
          type: boolean
          description: 'Optional. If set to true, any failure in the script will fail the deployment and ProvisioningState will be marked as Failed. If set to false, ProvisioningState would only reflect whether the run command was run or not by the extensions platform, it would not indicate whether script failed in case of script failures. See instance view of run command in case of script failures to see executionMessage, output, error: https://aka.ms/runcommandmanaged#get-execution-status-and-results '
          default: false
      type: object
      description: Describes the properties of a Virtual Machine run command.
    RunCommandParameterDefinition:
      properties:
        name:
          type: string
          description: The run command parameter name.
        type:
          type: string
          description: The run command parameter type.
        defaultValue:
          type: string
          description: The run command parameter default value.
        required:
          type: boolean
          description: The run command parameter required.
          default: false
      required:
      - name
      - type
      type: object
      description: Describes the properties of a run command parameter.
    VirtualMachineRunCommandInstanceView:
      properties:
        executionState:
          type: string
          description: Script execution status.
          enum:
          - Unknown
          - Pending
          - Running
          - Failed
          - Succeeded
          - TimedOut
          - Canceled
          x-ms-enum:
            name: ExecutionState
            modelAsString: true
        executionMessage:
          type: string
          description: Communicate script configuration errors or execution messages.
        exitCode:
          type: integer
          format: int32
          description: Exit code returned from script execution.
        output:
          type: string
          description: Script output stream.
        error:
          type: string
          description: Script error stream.
        startTime:
          type: string
          format: date-time
          description: Script start time.
        endTime:
          type: string
          format: date-time
          description: Script end time.
        statuses:
          type: array
          items:
            $ref: ./computeRPCommon.json#/definitions/InstanceViewStatus
          x-ms-identifiers: []
          description: The resource status information.
      type: object
      description: The instance view of a virtual machine run command.
    RunCommandDocumentBase:
      properties:
        $schema:
          type: string
          description: The VM run command schema.
        id:
          type: string
          description: The VM run command id.
        osType:
          type: string
          description: The Operating System type.
          enum:
          - Windows
          - Linux
          x-ms-enum:
            name: OperatingSystemTypes
            modelAsString: false
        label:
          type: string
          description: The VM run command label.
        description:
          type: string
          description: The VM run command description.
      required:
      - $schema
      - id
      - osType
      - label
      - description
      type: object
      description: Describes the properties of a Run Command metadata.
    VirtualMachineRunCommandsListResult:
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/VirtualMachineRunCommand'
          description: The list of run commands
        nextLink:
          type: string
          description: The uri to fetch the next page of run commands.
      required:
      - value
      type: object
      description: The List run command operation response
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow