Export (0) Print
Expand All

Get Role

Updated: July 23, 2014

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

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>

You must make sure that the request that is made to the management service is secure. For additional details, see Authenticating Service Management Requests.

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. For more information about versioning headers, see Service Management Versioning.

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

A successful operation returns status code 200 (OK). For information about status codes, see Service Management Status and Error Codes.

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

 

Response Header Description

x-ms-request-id

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

The format of the response body is as follows:


<PersistentVMRole xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <RoleName>name-of-the-virtual-machine</RoleName>
  <RoleType>PersistentVMRole</RoleType>
  <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>                    
          <Vip>virtual-ip-address-of-input-endpoint</Vip>
          <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>
      <PublicIPs>
        <PublicIP>
          <Name>name-of-public-ip</Name>
          <IdleTimeoutInMinutes>timeout-for-tcp-idle-connection</IdleTimeoutInMinutes>
        <PublicIP>
      <PublicIPs>
    </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>
    </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>
    <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.

VMImage

Specifies the name of the VM Image that was used to create the Virtual Machine. For more information, see Capture VM Image.

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. For more information about availability sets, see Manage the Availability of Virtual Machines.

DataVirtualHardDisks

Contains the parameters that were used to add a data disk to a Virtual Machine. For more information about data disks, see Manage Disks and Images.

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. For more information about Virtual Machine sizes, see Virtual Machine and Cloud Service Sizes for Azure.

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.

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.

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.

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. For more information, see High Availability and Disaster Recovery for SQL Server in Azure Virtual Machines.

Possible values are:

  • true

  • false

The default value is false.

Vip

Specifies the virtual IP address of the role.

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.

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

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.

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.

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.

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

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.

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.

SourceImageName

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

OS

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

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.

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

If this value is set to Private, the parameter will not be returned by Get Deployment. You can only specify one public parameter and one private parameter for a maximum of two parameters.

You can also use the Get-AzureRole cmdlet to retrieve information about roles.

Show:
© 2014 Microsoft