Virtual Machines - List

List virtual machines in a given lab.

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualmachines?api-version=2018-09-15
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualmachines?$expand={$expand}&$filter={$filter}&$top={$top}&$orderby={$orderby}&api-version=2018-09-15

URI Parameters

Name In Required Type Description
labName
path True
  • string

The name of the lab.

resourceGroupName
path True
  • string

The name of the resource group.

subscriptionId
path True
  • string

The subscription ID.

api-version
query True
  • string

Client API version.

$expand
query
  • string

Specify the $expand query. Example: 'properties($expand=artifacts,computeVm,networkInterface,applicableSchedule)'

$filter
query
  • string

The filter to apply to the operation. Example: '$filter=contains(name,'myName')

$orderby
query
  • string

The ordering expression for the results, using OData notation. Example: '$orderby=name desc'

$top
query
  • integer
int32

The maximum number of resources to return from the operation. Example: '$top=10'

Responses

Name Type Description
200 OK

OK

Other Status Codes

BadRequest

Security

azure_auth

OAuth2 Implicit Grant

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

Scopes

Name Description
user_impersonation Access Microsoft Azure

Examples

VirtualMachines_List

Sample Request

GET https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/myResourceGroup/providers/Microsoft.DevTestLab/labs/{devtestlab-name}/virtualmachines?api-version=2018-09-15

Sample Response

{
  "value": [
    {
      "properties": {
        "ownerObjectId": "",
        "ownerUserPrincipalName": "",
        "createdByUserId": "",
        "createdByUser": "",
        "createdDate": "2018-10-01T16:53:02.4830866-07:00",
        "computeId": "/subscriptions/{subscription-id}/resourceGroups/{devtestlab-name}-{virtualmachine-name}-{random-suffix}/providers/Microsoft.Compute/virtualMachines/{virtualmachine-name}",
        "osType": "Linux",
        "size": "Standard_A2_v2",
        "userName": "{user-name}",
        "labSubnetName": "{virtualnetwork-name}Subnet",
        "labVirtualNetworkId": "/subscriptions/{subscription-id}/resourcegroups/myResourceGroup/providers/microsoft.devtestlab/labs/{devtestlab-name}/virtualnetworks/{virtualnetwork-name}",
        "disallowPublicIpAddress": true,
        "artifactDeploymentStatus": {
          "artifactsApplied": 0,
          "totalArtifacts": 0
        },
        "galleryImageReference": {
          "offer": "UbuntuServer",
          "publisher": "Canonical",
          "sku": "16.04-LTS",
          "osType": "Linux",
          "version": "Latest"
        },
        "networkInterface": {},
        "allowClaim": true,
        "storageType": "Standard",
        "virtualMachineCreationSource": "FromGalleryImage",
        "dataDiskParameters": [],
        "provisioningState": "Succeeded",
        "uniqueIdentifier": "{unique-identifier}"
      },
      "id": "/subscriptions/{subscription-id}/resourcegroups/myResourceGroup/providers/microsoft.devtestlab/labs/{devtestlab-name}/virtualmachines/{virtualmachine-name}",
      "name": "{virtualmachine-name}",
      "type": "Microsoft.DevTestLab/labs/virtualMachines",
      "location": "{azure-location}",
      "tags": {
        "MyTag": "MyValue"
      }
    }
  ]
}

Definitions

ApplicableSchedule

Schedules applicable to a virtual machine. The schedules may have been defined on a VM or on lab level.

ArtifactDeploymentStatusProperties

Properties of an artifact deployment.

ArtifactInstallProperties

Properties of an artifact.

ArtifactParameterProperties

Properties of an artifact parameter.

AttachNewDataDiskOptions

Properties to attach new disk to the Virtual Machine.

CloudError

Error from a REST request.

CloudErrorBody

Body of an error from a REST request.

ComputeDataDisk

A data disks attached to a virtual machine.

ComputeVmInstanceViewStatus

Status information about a virtual machine.

ComputeVmProperties

Properties of a virtual machine returned by the Microsoft.Compute API.

DataDiskProperties

Request body for adding a new or existing data disk to a virtual machine.

DayDetails

Properties of a daily schedule.

EnableStatus

The status of the schedule (i.e. Enabled, Disabled)

GalleryImageReference

The reference information for an Azure Marketplace image.

HostCachingOptions

Caching option for a data disk (i.e. None, ReadOnly, ReadWrite).

HourDetails

Properties of an hourly schedule.

InboundNatRule

A rule for NAT - exposing a VM's port (backendPort) on the public IP address using a load balancer.

LabVirtualMachine

A virtual machine.

LabVirtualMachineList

The response of a list operation.

NetworkInterfaceProperties

Properties of a network interface.

NotificationSettings

Notification settings for a schedule.

Schedule

A schedule.

ScheduleCreationParameter

Properties for creating a schedule.

SharedPublicIpAddressConfiguration

Properties of a virtual machine that determine how it is connected to a load balancer.

StorageType

The storage type for the disk (i.e. Standard, Premium).

TransportProtocol

The transport protocol for the endpoint.

VirtualMachineCreationSource

Tells source of creation of lab virtual machine. Output property only.

WeekDetails

Properties of a weekly schedule.

ApplicableSchedule

Schedules applicable to a virtual machine. The schedules may have been defined on a VM or on lab level.

Name Type Description
id
  • string

The identifier of the resource.

location
  • string

The location of the resource.

name
  • string

The name of the resource.

properties.labVmsShutdown

The auto-shutdown schedule, if one has been set at the lab or lab resource level.

properties.labVmsStartup

The auto-startup schedule, if one has been set at the lab or lab resource level.

tags
  • object

The tags of the resource.

type
  • string

The type of the resource.

ArtifactDeploymentStatusProperties

Properties of an artifact deployment.

Name Type Description
artifactsApplied
  • integer

The total count of the artifacts that were successfully applied.

deploymentStatus
  • string

The deployment status of the artifact.

totalArtifacts
  • integer

The total count of the artifacts that were tentatively applied.

ArtifactInstallProperties

Properties of an artifact.

Name Type Description
artifactId
  • string

The artifact's identifier.

artifactTitle
  • string

The artifact's title.

deploymentStatusMessage
  • string

The status message from the deployment.

installTime
  • string

The time that the artifact starts to install on the virtual machine.

parameters

The parameters of the artifact.

status
  • string

The status of the artifact.

vmExtensionStatusMessage
  • string

The status message from the virtual machine extension.

ArtifactParameterProperties

Properties of an artifact parameter.

Name Type Description
name
  • string

The name of the artifact parameter.

value
  • string

The value of the artifact parameter.

AttachNewDataDiskOptions

Properties to attach new disk to the Virtual Machine.

Name Type Description
diskName
  • string

The name of the disk to be attached.

diskSizeGiB
  • integer

Size of the disk to be attached in GibiBytes.

diskType

The storage type for the disk (i.e. Standard, Premium).

CloudError

Error from a REST request.

Name Type Description
error

The cloud error that occurred

CloudErrorBody

Body of an error from a REST request.

Name Type Description
code
  • string

The error code.

details

Inner errors.

message
  • string

The error message.

target
  • string

The error target.

ComputeDataDisk

A data disks attached to a virtual machine.

Name Type Description
diskSizeGiB
  • integer

Gets data disk size in GiB.

diskUri
  • string

When backed by a blob, the URI of underlying blob.

managedDiskId
  • string

When backed by managed disk, this is the ID of the compute disk resource.

name
  • string

Gets data disk name.

ComputeVmInstanceViewStatus

Status information about a virtual machine.

Name Type Description
code
  • string

Gets the status Code.

displayStatus
  • string

Gets the short localizable label for the status.

message
  • string

Gets the message associated with the status.

ComputeVmProperties

Properties of a virtual machine returned by the Microsoft.Compute API.

Name Type Description
dataDiskIds
  • string[]

Gets data disks blob uri for the virtual machine.

dataDisks

Gets all data disks attached to the virtual machine.

networkInterfaceId
  • string

Gets the network interface ID of the virtual machine.

osDiskId
  • string

Gets OS disk blob uri for the virtual machine.

osType
  • string

Gets the OS type of the virtual machine.

statuses

Gets the statuses of the virtual machine.

vmSize
  • string

Gets the size of the virtual machine.

DataDiskProperties

Request body for adding a new or existing data disk to a virtual machine.

Name Type Description
attachNewDataDiskOptions

Specifies options to attach a new disk to the virtual machine.

existingLabDiskId
  • string

Specifies the existing lab disk id to attach to virtual machine.

hostCaching

Caching option for a data disk (i.e. None, ReadOnly, ReadWrite).

DayDetails

Properties of a daily schedule.

Name Type Description
time
  • string

The time of day the schedule will occur.

EnableStatus

The status of the schedule (i.e. Enabled, Disabled)

Name Type Description
Disabled
  • string
Enabled
  • string

GalleryImageReference

The reference information for an Azure Marketplace image.

Name Type Description
offer
  • string

The offer of the gallery image.

osType
  • string

The OS type of the gallery image.

publisher
  • string

The publisher of the gallery image.

sku
  • string

The SKU of the gallery image.

version
  • string

The version of the gallery image.

HostCachingOptions

Caching option for a data disk (i.e. None, ReadOnly, ReadWrite).

Name Type Description
None
  • string
ReadOnly
  • string
ReadWrite
  • string

HourDetails

Properties of an hourly schedule.

Name Type Description
minute
  • integer

Minutes of the hour the schedule will run.

InboundNatRule

A rule for NAT - exposing a VM's port (backendPort) on the public IP address using a load balancer.

Name Type Description
backendPort
  • integer

The port to which the external traffic will be redirected.

frontendPort
  • integer

The external endpoint port of the inbound connection. Possible values range between 1 and 65535, inclusive. If unspecified, a value will be allocated automatically.

transportProtocol

The transport protocol for the endpoint.

LabVirtualMachine

A virtual machine.

Name Type Description
id
  • string

The identifier of the resource.

location
  • string

The location of the resource.

name
  • string

The name of the resource.

properties.allowClaim
  • boolean

Indicates whether another user can take ownership of the virtual machine

properties.applicableSchedule

The applicable schedule for the virtual machine.

properties.artifactDeploymentStatus

The artifact deployment status for the virtual machine.

properties.artifacts

The artifacts to be installed on the virtual machine.

properties.computeId
  • string

The resource identifier (Microsoft.Compute) of the virtual machine.

properties.computeVm

The compute virtual machine properties.

properties.createdByUser
  • string

The email address of creator of the virtual machine.

properties.createdByUserId
  • string

The object identifier of the creator of the virtual machine.

properties.createdDate
  • string

The creation date of the virtual machine.

properties.customImageId
  • string

The custom image identifier of the virtual machine.

properties.dataDiskParameters

New or existing data disks to attach to the virtual machine after creation

properties.disallowPublicIpAddress
  • boolean

Indicates whether the virtual machine is to be created without a public IP address.

properties.environmentId
  • string

The resource ID of the environment that contains this virtual machine, if any.

properties.expirationDate
  • string

The expiration date for VM.

properties.fqdn
  • string

The fully-qualified domain name of the virtual machine.

properties.galleryImageReference

The Microsoft Azure Marketplace image reference of the virtual machine.

properties.isAuthenticationWithSshKey
  • boolean

Indicates whether this virtual machine uses an SSH key for authentication.

properties.labSubnetName
  • string

The lab subnet name of the virtual machine.

properties.labVirtualNetworkId
  • string

The lab virtual network identifier of the virtual machine.

properties.lastKnownPowerState
  • string

Last known compute power state captured in DTL

properties.networkInterface

The network interface properties.

properties.notes
  • string

The notes of the virtual machine.

properties.osType
  • string

The OS type of the virtual machine.

properties.ownerObjectId
  • string

The object identifier of the owner of the virtual machine.

properties.ownerUserPrincipalName
  • string

The user principal name of the virtual machine owner.

properties.password
  • string

The password of the virtual machine administrator.

properties.planId
  • string

The id of the plan associated with the virtual machine image

properties.provisioningState
  • string

The provisioning status of the resource.

properties.scheduleParameters

Virtual Machine schedules to be created

properties.size
  • string

The size of the virtual machine.

properties.sshKey
  • string

The SSH key of the virtual machine administrator.

properties.storageType
  • string

Storage type to use for virtual machine (i.e. Standard, Premium).

properties.uniqueIdentifier
  • string

The unique immutable identifier of a resource (Guid).

properties.userName
  • string

The user name of the virtual machine.

properties.virtualMachineCreationSource

Tells source of creation of lab virtual machine. Output property only.

tags
  • object

The tags of the resource.

type
  • string

The type of the resource.

LabVirtualMachineList

The response of a list operation.

Name Type Description
nextLink
  • string

Link for next set of results.

value

Results of the list operation.

NetworkInterfaceProperties

Properties of a network interface.

Name Type Description
dnsName
  • string

The DNS name.

privateIpAddress
  • string

The private IP address.

publicIpAddress
  • string

The public IP address.

publicIpAddressId
  • string

The resource ID of the public IP address.

rdpAuthority
  • string

The RdpAuthority property is a server DNS host name or IP address followed by the service port number for RDP (Remote Desktop Protocol).

sharedPublicIpAddressConfiguration

The configuration for sharing a public IP address across multiple virtual machines.

sshAuthority
  • string

The SshAuthority property is a server DNS host name or IP address followed by the service port number for SSH.

subnetId
  • string

The resource ID of the sub net.

virtualNetworkId
  • string

The resource ID of the virtual network.

NotificationSettings

Notification settings for a schedule.

Name Type Description
emailRecipient
  • string

The email recipient to send notifications to (can be a list of semi-colon separated email addresses).

notificationLocale
  • string

The locale to use when sending a notification (fallback for unsupported languages is EN).

status

If notifications are enabled for this schedule (i.e. Enabled, Disabled).

timeInMinutes
  • integer

Time in minutes before event at which notification will be sent.

webhookUrl
  • string

The webhook URL to which the notification will be sent.

Schedule

A schedule.

Name Type Description
id
  • string

The identifier of the resource.

location
  • string

The location of the resource.

name
  • string

The name of the resource.

properties.createdDate
  • string

The creation date of the schedule.

properties.dailyRecurrence

If the schedule will occur once each day of the week, specify the daily recurrence.

properties.hourlyRecurrence

If the schedule will occur multiple times a day, specify the hourly recurrence.

properties.notificationSettings

Notification settings.

properties.provisioningState
  • string

The provisioning status of the resource.

properties.status

The status of the schedule (i.e. Enabled, Disabled)

properties.targetResourceId
  • string

The resource ID to which the schedule belongs

properties.taskType
  • string

The task type of the schedule (e.g. LabVmsShutdownTask, LabVmAutoStart).

properties.timeZoneId
  • string

The time zone ID (e.g. Pacific Standard time).

properties.uniqueIdentifier
  • string

The unique immutable identifier of a resource (Guid).

properties.weeklyRecurrence

If the schedule will occur only some days of the week, specify the weekly recurrence.

tags
  • object

The tags of the resource.

type
  • string

The type of the resource.

ScheduleCreationParameter

Properties for creating a schedule.

Name Type Description
location
  • string

The location of the new virtual machine or environment

name
  • string

The name of the virtual machine or environment

properties.dailyRecurrence

If the schedule will occur once each day of the week, specify the daily recurrence.

properties.hourlyRecurrence

If the schedule will occur multiple times a day, specify the hourly recurrence.

properties.notificationSettings

Notification settings.

properties.status

The status of the schedule (i.e. Enabled, Disabled)

properties.targetResourceId
  • string

The resource ID to which the schedule belongs

properties.taskType
  • string

The task type of the schedule (e.g. LabVmsShutdownTask, LabVmAutoStart).

properties.timeZoneId
  • string

The time zone ID (e.g. Pacific Standard time).

properties.weeklyRecurrence

If the schedule will occur only some days of the week, specify the weekly recurrence.

tags
  • object

The tags of the resource.

SharedPublicIpAddressConfiguration

Properties of a virtual machine that determine how it is connected to a load balancer.

Name Type Description
inboundNatRules

The incoming NAT rules

StorageType

The storage type for the disk (i.e. Standard, Premium).

Name Type Description
Premium
  • string
Standard
  • string
StandardSSD
  • string

TransportProtocol

The transport protocol for the endpoint.

Name Type Description
Tcp
  • string
Udp
  • string

VirtualMachineCreationSource

Tells source of creation of lab virtual machine. Output property only.

Name Type Description
FromCustomImage
  • string
FromGalleryImage
  • string
FromSharedGalleryImage
  • string

WeekDetails

Properties of a weekly schedule.

Name Type Description
time
  • string

The time of the day the schedule will occur.

weekdays
  • string[]

The days of the week for which the schedule is set (e.g. Sunday, Monday, Tuesday, etc.).