Share via


Get Role

 

The Get Role operation retrieves information about the specified Virtual Machine.

Request

The Get Role request may be specified as follows. Replace <subscription-id> with the subscription ID, <cloudservice-name> with the name of the cloud service, <deployment-name> with the name of the deployment, and <role-name> with the name of the Virtual Machine.

Method

Request URI

GET

https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments/<deployment-name>/roles/<role-name>

URI Parameters

None.

Request Headers

The following table describes the request headers.

Request Header

Description

x-ms-version

Required. Specifies the version of the operation to use for this request. This header should be set to 2012-03-01 or higher.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

A successful operation returns status code 200 (OK).

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers.

Response Header

Description

x-ms-request-id

A value that uniquely identifies a request made against the management service.

Response Body

The format of the response body is as follows:

<PersistentVMRole xmlns="https://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <RoleName>name-of-the-virtual-machine</RoleName>
  <RoleType>PersistentVMRole</RoleType>
  <LicenseType>type-of-license</LicenseType>
  <VMImage>name-of-vm-image</VMImage>
  <MediaLocation>path-to-vhds</MediaLocation>      
  <ConfigurationSets>
    <ConfigurationSet>
      <ConfigurationSetType>NetworkConfiguration</ConfigurationSetType>          
      <InputEndpoints>
        <InputEndpoint>                
          <LoadBalancedEndpointSetName>name-of-load-balanced-set</LoadBalancedEndpointSetName>
          <LocalPort>local-port-number</LocalPort>
          <Name>name-of-endpoint</Name>
          <Port>external-port-number</Port>
          <LoadBalancerProbe>
            <Path>path-of-probe</Path>
            <Port>port-assigned-to-probe</Port>
            <Protocol>probe-protocol</Protocol>                    
          </LoadBalancerProbe>   
          <Protocol>endpoint-protocol</Protocol>
          <EnableDirectServerReturn>enable-direct-server-return</EnableDirectServerReturn>
          <LoadBalancerName>name-of-internal-loadbalancer</LoadBalancerName>
          <IdleTimeoutInMinutes>timeout-for-tcp-idle-connection</IdleTimeoutInMinutes>
        </InputEndpoint>
      </InputEndpoints>
      <SubnetNames>
        <SubnetName>name-of-subnet</SubnetName>
      </SubnetNames>    
      <StaticVirtualNetworkIPAddress>ip-address</StaticVirtualNetworkIPAddress>
      <NetworkSecurityGroup>network-security-group</NetworkSecurityGroup>
      <PublicIPs>
        <PublicIP>
          <Name>name-of-public-ip</Name>
          <IdleTimeoutInMinutes>timeout-for-tcp-idle-connection</IdleTimeoutInMinutes>
          <DomainNameLabel>domain-name</DomainNameLabel>
        <PublicIP>
      <PublicIPs>
      <NetworkInterfaces>
        <NetworkInterface>
          <Name>interface-name</Name>
          <IPConfigurations>
            <IPConfiguration>
              <SubnetName>subnet-name</SubnetName>
              <StaticVirtualNetworkIPAddress>ip-address</StaticVirtualNetworkIPAddress>
            </IPConfiguration>
          </IPConfigurations>
        </NetworkInterface>
      <NetworkInterfaces>
    </ConfigurationSet>
  </ConfigurationSets>
  <ResourceExtensionReferences>
    <ResourceExtensionReference>
      <ReferenceName>name-of-reference</ReferenceName>
      <Publisher>name-of-publisher</Publisher>
      <Name>name-of-extension</Name>
      <Version>version-of-extension</Version>
      <ResourceExtensionParameterValues>
        <ResourceExtensionParameterValue>
          <Key>name-of-parameter-key</Key>
          <Value>parameter-value</Value>
          <Type>type-of-parameter</Type>
        </ResourceExtensionParameterValue>
      </ResourceExtensionParameterValues>
      <State>state-of-resource</State>
    </ResourceExtensionReference>
  </ResourceExtensionReferences>
  <AvailabilitySetName>name-of-availability-set</AvailabilitySetName>
  <DataVirtualHardDisks>
    <DataVirtualHardDisk>
      <HostCaching>host-caching-mode-of-data-disk</HostCaching> 
      <DiskName>new-or-existing-disk-name</DiskName>
      <Lun>logical-unit-number-of-data-disk</Lun>
      <LogicalDiskSizeInGB>size-of-data-disk</LogicalDiskSizeInGB>            
      <MediaLink>path-to-vhd</MediaLink>
      <IOType>IO-type<IOType>
    </DataVirtualHardDisk>
  </DataVirtualHardDisks>
  <OSVirtualHardDisk>
    <HostCaching>host-caching-mode-of-os-disk</HostCaching>    
    <DiskName>name-of-os-disk</DiskName>                    
    <MediaLink>path-to-vhd</MediaLink>
    <SourceImageName>image-used-to-create-os-disk</SourceImageName>
    <IOType>IO-type<IOType>
    <OS>operating-system-on-os-disk</OS>
  </OSVirtualHardDisk>      
  <RoleSize>size-of-instance</RoleSize>
  <ProvisionGuestAgent>install-an-agent</ProvisionGuestAgent>
  <DefaultWinRmCertificateThumbprint>winrm-cert-thumbprint</DefaultWinRmCertificateThumbprint>     
</PersistentVMRole>

The following table describes the elements in the response body.

Element name

Description

RoleName

Specifies the name of the Virtual Machine.

RoleType

Specifies the type of role that is used. For Virtual Machines, this must be PersistentVMRole.

LicenseType

Optional. Specifies that the image or disk that is being used was licensed on-premises. This element is only used for images that contain the Windows Server operating system.

Possible values are:

  • Windows_Client

  • Windows_Server

VMImage

Specifies the name of the VM Image that was used to create the Virtual Machine.

The VMImage element is only available using version 2014-02-01 or higher.

MediaLocation

Specifies the path to the VHD files that are associated with the VM Image.

The MediaLocation element is only available using version 2014-02-01 or higher.

ConfigurationSets

Contains a collection of configuration sets that define system and application settings.

ResourceExtensionReferences

Optional. Contains a collection of resource extensions that are installed on the Virtual Machine. This element is used if ProvisionGuestAgent is set to true.

AvailabilitySetName

Specifies the name of a collection of Virtual Machines. Virtual Machines specified in the same availability set are allocated to different nodes to maximize availability.

DataVirtualHardDisks

Contains the parameters that were used to add a data disk to a Virtual Machine.

OSVirtualHardDisk

Contains the parameters that were used to create the operating system disk for a Virtual Machine.

RoleSize

Specifies the size of the Virtual Machine. The default size is Small.

ProvisionGuestAgent

Optional. Indicates whether the VM Agent is installed on the Virtual Machine. To run a resource extension in a Virtual Machine, this service must be installed.

Possible values are:

  • true

  • false

DefaultWinRmCertificateThumbprint

Specifies the read-only thumbprint of the certificate that is used with the HTTPS listener for WinRM.

ConfigurationSets

Contains a collection of configuration sets that contain system and application configuration settings.

Element name

Description

ConfigurationSetType

Specifies the configuration type for the configuration set. This is currently always set to NetworkConfiguration.

InputEndpoints

Contains a collection of external endpoints for the Virtual Machine.

SubnetNames

Contains a list of subnets to which the Virtual Machine will belong.

StaticVirtualNetworkIPAddress

Specifies the internal IP address for the Virtual Machine in a Virtual Network. If this element is specified, the SubnetNames element will contain only one subnet. The IP address specified in this element belongs to the subnet that is defined in SubnetNames.

The StaticVirtualNetworkIPAddress element is only available using version 2013-11-01 or higher.

NetworkSecurityGroup

Optional. Represents the name of the Network Security Group that will be associated with the Virtual Machine. Network Security Group must exist in the context of subscription and be created in same region to which the virtual machine will be deployed.

The NetworkSecurityGroup element is only available using version 2014-10-01 or higher.

PublicIPs

Optional. Contains a public IP address that can be used in addition to default virtual IP address for the Virtual Machine.

The PublicIPs element is only available using version 2014-05-01 or higher.

NetworkInterfaces

Optional, A set of secondary network interfaces. The number of secondary network interfaces allowed depends on the size of the virtual machine.

The NetworkInterfaces element is only available using version 2014-08-01 or higher.

InputEndpoints

Contains a collection of external endpoints for the Virtual Machine.

Element name

Description

LoadBalancedEndpointSetName

Specifies a name for a set of load-balanced endpoints.

LocalPort

Specifies the internal port on which the Virtual Machine is listening.

Name

Specifies the name of the external endpoint.

Port

Specifies the external port to use for the endpoint.

LoadBalancerProbe

Contains properties that define the endpoint settings that the load balancer uses to monitor the availability of the Virtual Machine before forwarding traffic to it.

Protocol

Specifies the transport protocol for the endpoint.

Possible Values are:

  • TCP

  • UDP

EnableDirectServerReturn

Specifies whether the endpoint uses Direct Server Return. The EnableDirectServerReturn element is not supported for RDP, SSH, or WinRM endpoints and it is not supported when the public port and local port of an endpoint are different. It is recommended that this element is only used when setting up Virtual Machines for SQL Server and AlwaysOn Availability Groups.

Possible values are:

  • true

  • false

The default value is false.

LoadBalancerName

Optional. Specifies the name of the internal load balancer that is associated with this endpoint.

The LoadBalancerName element is only available using version 2014-05-01 or higher.

IdleTimeoutInMinutes

Optional. Specifies the timeout for the TCP idle connection. The value can be set between 4 and 30 minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP.

The IdleTimeoutInMinutes element is only available using version 2014-06-01 or higher.

LoadBalancerProbe

Contains properties that define the endpoint settings that the load balancer uses to monitor the availability of the Virtual Machine before forwarding traffic to it.

Element name

Description

Path

Specifies the relative path to inspect to determine the availability status of the Virtual Machine. If Protocol is set to TCP, this value must be NULL.

Example:

path

The probe will use https://example.com/path to perform the probe.

Port

Specifies the port to use to inspect the availability status of the Virtual Machine.

Protocol

Specifies the protocol to use to inspect the availability status of the Virtual Machine.

Possible values are:

  • HTTP

  • TCP

PublicIPs

Contains a public IP address that can be used in addition to default virtual IP address for the Virtual Machine.

Element name

Description

PublicIP

Required. Specifies an additional IP public address that can be used to communicate with the Virtual Machine.

Name

Required. Specifies the name of the public IP address.

IdleTimeoutInMinutes

Optional. Specifies the timeout for the TCP idle connection. The value can be set between 4 and 30 minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP.

The IdleTimeoutInMinutes element is only available using version 2014-06-01 or higher.

DomainNameLabel

Optional. Specifies the domain name label for the public IP.

The DomainNameLabel element is only available using version 2015-03-01 or higher.

NetworkInterfaces

Contains a set of secondary network interfaces.

Element name

Description

NetworkInterface

Required. Specifies a secondary network interface.

Name

Required, Specifies the name of the secondary network interface.

IPConfigurations

Required. Specifies a set of IP address configurations for a secondary network interface.

IPConfigurations

Specifies a set of IP address configurations for a secondary network interface.

Element name

Description

IPConfiguration

Required. Specifies an IP address configuration for a secondary network interface.

Currently only one IP address configuration is supported for a secondary network interface.

SubnetName

Required. Specifies the name of the virtual network subnet that this IP address configuration belongs.

Address

Required, Specifies the internal IP address configured for a secondary network interface.

SubnetNames

Contains a list of subnets to which the Virtual Machine will belong.

Element name

Description

SubnetName

Specifies the name of a subnet to which the Virtual Machine belongs.

DataVirtualHardDisks

Contains the parameters that are used to add a data disk to a Virtual Machine.

Element name

Description

DataVirtualHardDisk

Specifies the properties that are used to create a data disk.

Example: http://contoso.blob.core.windows.net/disks/mydatadisk.vhd

HostCaching

Specifies the caching behavior of the data disk for read/write efficiency. Setting this property impacts the consistency of the disk.

Possible values are:

  • None

  • ReadOnly

  • ReadWrite

The default value is None.

DiskName

Specifies the name of the data disk.

Lun

Specifies the Logical Unit Number (LUN) for the data disk.

Valid LUN values are 0 through 31.

LogicalDiskSizeInGB

Specifies the size, in GB, of an empty disk to be attached to the Virtual Machine.

MediaLink

Specifies the location of the VHD that is associated with the data disk.

Example: http://contoso.blob.core.indows.net/disks/mydatadisk.vhd

IOType

This property identifies the type of the storage account for the backing VHD.

If the backing VHD is in an Provisioned Storage account, “Provisioned” is returned otherwise “Standard” is returned.

Note: This value is populated by Azure platform when the disk is created, not by the user.

This property is only returned with a version header of 2014-10-01 or newer.

OSVirtualHardDisk

Contains the parameters that are used to create the operating system disk for a Virtual Machine.

Element name

Description

HostCaching

Specifies the caching mode of the operating system disk. This setting impacts the consistency and performance of the disk.

Possible values are:

  • ReadOnly

  • ReadWrite

The default value is ReadWrite.

DiskName

Specifies the name an operating system disk.

MediaLink

Specifies the location of the VHD that is associated with the operating system disk.

Example: http://contoso.blob.core.indows.net/disks/mydatadisk.vhd

SourceImageName

Specifies the name of the image that was used to create the Virtual Machine.

IOType

This property identifies the type of the storage account for the backing VHD.

If the backing VHD is in an Provisioned Storage account, “Provisioned” is returned otherwise “Standard” is returned.

Note: This value is populated by Azure platform when the disk is created, not by the user.

This property is only returned with a version header of 2014-10-01 or newer

OS

Specifies the operating system that is running in the Virtual Machine.

ResourceExtensionReferences

Contains a collection of resource extensions that are to be installed on the Virtual Machine. A resource extension is a software component that is installed on the Virtual Machine. The VM Agent must be installed on the Virtual Machine to install resource extensions.

Element name

Description

ResourceExtensionReference

Required. Specifies the properties of a resource extension that should be installed on the Virtual Machine.

ReferenceName

Required. Specifies the reference name of the resource extension.

Publisher

Required. Specifies the name of the publisher who created the resource extension. You can use List Resource Extensions to find the publisher name of a resource extension.

Name

Required. Specifies the name of the resource extension. You can use List Resource Extensions to find the names of available resource extensions.

Version

Required. Specifies the version of the resource extension. You can use List Resource Extension Versions to find the version of the resource extension.

ResourceExtensionParameterValues

Optional. Contains a collection of parameters that are passed to the resource extension when it is installed.

State

Optional. Specifies the state of the resource extension.

Possible values are:

  • Enable

  • Disable

The default value is Enable.

ResourceExtensionParameterValues

Contains a collection of parameters that are passed to the resource extension when it is installed.

Element name

Description

ResourceExtensionParameterValue

Required. Specifies the key, value, and type of the parameter.

Key

Required. Specifies the key of the parameter.

Value

Required. Specifies the base-64 encoded value of the parameter.

Type

Required. Specifies the type for the resource extension.

Possible values are:

  • Public

  • Private