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

LabVirtualMachineList

OK

Other Status Codes

CloudError

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/{subscriptionId}/resourceGroups/resourceGroupName/providers/Microsoft.DevTestLab/labs/{labName}/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/{subscriptionId}/resourceGroups/{labName}-{vmName}-{randomSuffix}/providers/Microsoft.Compute/virtualMachines/{vmName}",
        "osType": "Linux",
        "size": "Standard_A2_v2",
        "userName": "{userName}",
        "labSubnetName": "{virtualNetworkName}Subnet",
        "labVirtualNetworkId": "/subscriptions/{subscriptionId}/resourcegroups/resourceGroupName/providers/microsoft.devtestlab/labs/{labName}/virtualnetworks/{virtualNetworkName}",
        "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": "{uniqueIdentifier}"
      },
      "id": "/subscriptions/{subscriptionId}/resourcegroups/resourceGroupName/providers/microsoft.devtestlab/labs/{labName}/virtualmachines/{vmName}",
      "name": "{vmName}",
      "type": "Microsoft.DevTestLab/labs/virtualMachines",
      "location": "{location}",
      "tags": {
        "tagName1": "tagValue1"
      }
    }
  ]
}

Definitions

Name Description
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

Schedule

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

properties.labVmsStartup

Schedule

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

ArtifactParameterProperties[]

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

StorageType

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

CloudError

Error from a REST request.

Name Type Description
error

CloudErrorBody

The cloud error that occurred

CloudErrorBody

Body of an error from a REST request.

Name Type Description
code

string

The error code.

details

CloudErrorBody[]

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

ComputeDataDisk[]

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

ComputeVmInstanceViewStatus[]

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

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

HostCachingOptions

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

TransportProtocol

The transport protocol for the endpoint.

LabVirtualMachine

A virtual machine.

Name Type Default Value 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

False

Indicates whether another user can take ownership of the virtual machine

properties.applicableSchedule

ApplicableSchedule

The applicable schedule for the virtual machine.

properties.artifactDeploymentStatus

ArtifactDeploymentStatusProperties

The artifact deployment status for the virtual machine.

properties.artifacts

ArtifactInstallProperties[]

The artifacts to be installed on the virtual machine.

properties.computeId

string

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

properties.computeVm

ComputeVmProperties

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

DataDiskProperties[]

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

properties.disallowPublicIpAddress

boolean

False

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

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

NetworkInterfaceProperties

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

dynamicValue

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

ScheduleCreationParameter[]

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

labStorageType

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

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

LabVirtualMachine[]

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

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 Default Value 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

EnableStatus

Disabled

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 Default Value 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

DayDetails

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

properties.hourlyRecurrence

HourDetails

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

properties.notificationSettings

NotificationSettings

Notification settings.

properties.provisioningState

string

The provisioning status of the resource.

properties.status

EnableStatus

Disabled

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. China Standard Time, Greenland Standard Time, Pacific Standard time, etc.). The possible values for this property can be found in IReadOnlyCollection<string> TimeZoneConverter.TZConvert.KnownWindowsTimeZoneIds (https://github.com/mattjohnsonpint/TimeZoneConverter/blob/main/README.md)

properties.uniqueIdentifier

string

The unique immutable identifier of a resource (Guid).

properties.weeklyRecurrence

WeekDetails

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 Default Value Description
location

string

The location of the new virtual machine or environment

name

string

The name of the virtual machine or environment

properties.dailyRecurrence

DayDetails

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

properties.hourlyRecurrence

HourDetails

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

properties.notificationSettings

NotificationSettings

Notification settings.

properties.status

EnableStatus

Disabled

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. China Standard Time, Greenland Standard Time, Pacific Standard time, etc.). The possible values for this property can be found in IReadOnlyCollection<string> TimeZoneConverter.TZConvert.KnownWindowsTimeZoneIds (https://github.com/mattjohnsonpint/TimeZoneConverter/blob/main/README.md)

properties.weeklyRecurrence

WeekDetails

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

InboundNatRule[]

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.).