Get Role

Article
08/04/2016

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

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.

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