Microsoft Azure SessionHost API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector SessionHost API
schemes:
- https
tags:
- name: SessionHost
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DesktopVirtualization/hostPools/{hostPoolName}/sessionHosts/{sessionHostName}
  : get:
      tags:
      - SessionHost
      operationId: microsoftAzureSessionhostsGet
      description: Get a session host.
      x-ms-examples:
        SessionHost_Get:
          $ref: ./examples/SessionHost_Get.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/parameters/HostPoolNameParameter'
      - $ref: '#/parameters/SessionHostNameParameter'
      responses:
        '200':
          description: Successfully retrieved session host.
          schema:
            $ref: '#/definitions/SessionHost'
        default:
          description: Automation error response describing why the operation failed.
          schema:
            $ref: '#/definitions/CloudError'
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname
    delete:
      tags:
      - SessionHost
      operationId: microsoftAzureSessionhostsDelete
      description: Remove a SessionHost.
      x-ms-examples:
        SessionHost_Delete:
          $ref: ./examples/SessionHost_Delete.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/parameters/HostPoolNameParameter'
      - $ref: '#/parameters/SessionHostNameParameter'
      - name: force
        in: query
        required: false
        type: boolean
        description: Force flag to force sessionHost deletion even when userSession exists.
      responses:
        '200':
          description: Successfully removed session host.
        '204':
          description: Session host does not exist.
        default:
          description: Automation error response describing why the operation failed.
          schema:
            $ref: '#/definitions/CloudError'
      summary: Microsoft Azure Delete Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname
    patch:
      tags:
      - SessionHost
      operationId: microsoftAzureSessionhostsUpdate
      description: Update a session host.
      x-ms-examples:
        SessionHost_Update:
          $ref: ./examples/SessionHost_Update.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/parameters/HostPoolNameParameter'
      - $ref: '#/parameters/SessionHostNameParameter'
      - name: sessionHost
        description: Object containing SessionHost definitions.
        in: body
        required: false
        schema:
          $ref: '#/definitions/SessionHostPatch'
      - name: force
        in: query
        required: false
        type: boolean
        description: Force flag to update assign, unassign or reassign personal desktop.
      responses:
        '200':
          description: Successfully updated session host.
          schema:
            $ref: '#/definitions/SessionHost'
        default:
          description: Automation error response describing why the operation failed.
          schema:
            $ref: '#/definitions/CloudError'
      summary: Microsoft Azure Patch Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DesktopVirtualization/hostPools/{hostPoolName}/sessionHosts
  : get:
      tags:
      - SessionHost
      operationId: microsoftAzureSessionhostsList
      description: List sessionHosts.
      x-ms-examples:
        SessionHost_List:
          $ref: ./examples/SessionHost_List.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/parameters/HostPoolNameParameter'
      - name: pageSize
        in: query
        required: false
        type: integer
        format: int32
        description: Number of items per page.
      - name: isDescending
        in: query
        required: false
        type: boolean
        description: Indicates whether the collection is descending.
      - name: initialSkip
        in: query
        required: false
        type: integer
        format: int32
        description: Initial number of items to skip.
      responses:
        '200':
          description: Successfully retrieved session hosts in host pool.
          schema:
            $ref: '#/definitions/SessionHostList'
        default:
          description: Automation error response describing why the operation failed.
          schema:
            $ref: '#/definitions/CloudError'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DesktopVirtualization/hostPools/{hostPoolName}/sessionHosts/{sessionHostName}/retryProvisioning
  : post:
      tags:
      - SessionHost
      operationId: microsoftAzureSessionhostRetryprovisioning
      description: Retry provisioning on a SessionHost.
      x-ms-examples:
        SessionHost_RetryProvisioning_Post:
          $ref: ./examples/SessionHost_RetryProvisioning_Post.json
      parameters:
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../common-types/resource-management/v3/types.json#/parameters/ResourceGroupNameParameter
      - $ref: '#/parameters/HostPoolNameParameter'
      - $ref: '#/parameters/SessionHostNameParameter'
      responses:
        '200':
          description: Successfully started provisioning retry on the sessionHost.
        default:
          description: Automation error response describing why the operation failed.
          schema:
            $ref: '#/definitions/CloudError'
      summary: Microsoft Azure Post Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname Retryprovisioning
definitions:
  SessionHostProperties:
    description: Schema for SessionHost properties.
    type: object
    properties:
      objectId:
        type: string
        description: ObjectId of SessionHost. (internal use)
        readOnly: true
      lastHeartBeat:
        format: date-time
        type: string
        description: Last heart beat from SessionHost.
      sessions:
        type: integer
        format: int32
        description: Number of sessions on SessionHost.
      agentVersion:
        type: string
        description: Version of agent on SessionHost.
      allowNewSession:
        type: boolean
        description: Allow a new session.
      virtualMachineId:
        type: string
        description: Virtual Machine Id of SessionHost's underlying virtual machine.
        readOnly: true
      resourceId:
        type: string
        description: Resource Id of SessionHost's underlying virtual machine.
        readOnly: true
      assignedUser:
        type: string
        description: User assigned to SessionHost.
      friendlyName:
        type: string
        description: Friendly name of SessionHost
      status:
        enum:
        - Available
        - Unavailable
        - Shutdown
        - Disconnected
        - Upgrading
        - UpgradeFailed
        - NoHeartbeat
        - NotJoinedToDomain
        - DomainTrustRelationshipLost
        - SxSStackListenerNotReady
        - FSLogixNotHealthy
        - NeedsAssistance
        x-ms-enum:
          name: Status
          modelAsString: true
          values:
          - value: Available
            description: Session Host has passed all the health checks and is available to handle connections.
          - value: Unavailable
            description: Session Host is either turned off or has failed critical health checks which is causing service not to be able to route connections to this session host. Note this replaces previous 'NoHeartBeat' status.
          - value: Shutdown
            description: Session Host is shutdown - RD Agent reported session host to be stopped or deallocated.
          - value: Disconnected
            description: The Session Host is unavailable because it is currently disconnected.
          - value: Upgrading
            description: 'Session Host is unavailable because currently an upgrade of RDAgent/side-by-side stack is in progress. Note: this state will be removed once the upgrade completes and the host is able to accept connections.'
          - value: UpgradeFailed
            description: Session Host is unavailable because the critical component upgrade (agent, side-by-side stack, etc.) failed.
          - value: NoHeartbeat
            description: The Session Host is not heart beating.
          - value: NotJoinedToDomain
            description: SessionHost is not joined to domain.
          - value: DomainTrustRelationshipLost
            description: SessionHost's domain trust relationship lost
          - value: SxSStackListenerNotReady
            description: SxS stack installed on the SessionHost is not ready to receive connections.
          - value: FSLogixNotHealthy
            description: FSLogix is in an unhealthy state on the session host.
          - value: NeedsAssistance
            description: New status to inform admins that the health on their endpoint needs to be fixed. The connections might not fail, as these issues are not fatal.
        type: string
        description: Status for a SessionHost.
      statusTimestamp:
        format: date-time
        type: string
        description: The timestamp of the status.
        readOnly: true
      osVersion:
        type: string
        description: The version of the OS on the session host.
      sxSStackVersion:
        type: string
        description: The version of the side by side stack on the session host.
      updateState:
        enum:
        - Initial
        - Pending
        - Started
        - Succeeded
        - Failed
        x-ms-enum:
          name: UpdateState
          modelAsString: true
        type: string
        description: Update state of a SessionHost.
      lastUpdateTime:
        format: date-time
        type: string
        description: The timestamp of the last update.
        readOnly: true
      updateErrorMessage:
        type: string
        description: The error message.
      lastSessionHostUpdateTime:
        type: string
        format: date-time
        description: The last time update was completed.
        readOnly: true
      sessionHostConfiguration:
        type: string
        description: SessionHostConfiguration version reference at the time the update is initiated, in the format of date time.
        readOnly: true
      sessionHostHealthCheckResults:
        type: array
        readOnly: true
        description: List of SessionHostHealthCheckReports
        items:
          $ref: '#/definitions/SessionHostHealthCheckReport'
  SessionHost:
    type: object
    description: Represents a SessionHost definition.
    allOf:
    - $ref: ../../../../../common-types/resource-management/v1/types.json#/definitions/Resource
    properties:
      systemData:
        $ref: ../../../../../common-types/resource-management/v2/types.json#/definitions/systemData
        description: Metadata pertaining to creation and last modification of the resource.
      properties:
        description: Detailed properties for SessionHost
        x-ms-client-flatten: true
        $ref: '#/definitions/SessionHostProperties'
  SessionHostPatchProperties:
    description: SessionHost properties that can be patched.
    type: object
    properties:
      allowNewSession:
        type: boolean
        description: Allow a new session.
      assignedUser:
        type: string
        description: User assigned to SessionHost.
      friendlyName:
        type: string
        description: Friendly name of SessionHost
  SessionHostHealthCheckReport:
    type: object
    description: The report for session host information.
    properties:
      healthCheckName:
        enum:
        - DomainJoinedCheck
        - DomainTrustCheck
        - FSLogixHealthCheck
        - SxSStackListenerCheck
        - UrlsAccessibleCheck
        - MonitoringAgentCheck
        - DomainReachable
        - WebRTCRedirectorCheck
        - SupportedEncryptionCheck
        - MetaDataServiceCheck
        - AppAttachHealthCheck
        x-ms-enum:
          name: HealthCheckName
          modelAsString: true
          values:
          - value: DomainJoinedCheck
            description: Verifies the SessionHost is joined to a domain. If this check fails is classified as fatal as no connection can succeed if the SessionHost is not joined to the domain. (Currently Enabled)
          - value: DomainTrustCheck
            description: Verifies the SessionHost is not experiencing domain trust issues that will prevent authentication on SessionHost at connection time when session is created. If this check fails is classified as fatal as no connection can succeed if we cannot reach the domain for authentication on the SessionHost. (Currently Enabled)
          - value: FSLogixHealthCheck
            description: Verifies the FSLogix service is up and running to make sure users' profiles are loaded in the session. If this check fails is classified as fatal as even if the connection can succeed, user experience is bad as the user profile cannot be loaded and user will get a temporary profile in the session. (Currently Disabled)
          - value: SxSStackListenerCheck
            description: Verifies that the SxS stack is up and running so connections can succeed. If this check fails is classified as fatal as no connection can succeed if the SxS stack is not ready. (Currently Enabled)
          - value: UrlsAccessibleCheck
            description: 'Verifies that the required WVD service and Geneva URLs are reachable from the SessionHost. These URLs are: RdTokenUri, RdBrokerURI, RdDiagnosticsUri and storage blob URLs for agent monitoring (geneva). If this check fails, it is non fatal and the machine still can service connections, main issue may be that monitoring agent is unable to store warm path data (logs, operations ...). (Currently Disabled)'
          - value: MonitoringAgentCheck
            description: Verifies that the required Geneva agent is running. If this check fails, it is non fatal and the machine still can service connections, main issue may be that monitoring agent is missing or running (possibly) older version. (Currently Enabled)
          - value: DomainReachable
            description: Verifies the domain the SessionHost is joined to is still reachable. If this check fails is classified as fatal as no connection can succeed if the domain the SessionHost is joined is not reachable at the time of connection. (Currently Disabled)
          - value: WebRTCRedirectorCheck
            description: Verifies whether the WebRTCRedirector component is healthy. The WebRTCRedirector component is used to optimize video and audio performance in Microsoft Teams. This checks whether the component is still running, and whether there is a higher version available. If this check fails, it is non fatal and the machine still can service connections, main issue may be the WebRTCRedirector component has to be restarted or updated. (Currently Disabled)
          - value: SupportedEncryptionCheck
            description: Verifies the value of SecurityLayer registration key. If the value is 0 (SecurityLayer.RDP) this check fails with Error code = NativeMethodErrorCode.E_FAIL and is fatal. If the value is 1 (SecurityLayer.Negotiate) this check fails with Error code = NativeMethodErrorCode.ERROR_SUCCESS and is non fatal. (Currently Disabled)
          - value: MetaDataServiceCheck
            description: Verifies the metadata service is accessible and return compute properties. (Currently Enabled)
          - value: AppAttachHealthCheck
            description: Verifies that the AppAttachService is healthy (there were no issues during package staging). The AppAttachService is used to enable the staging/registration (and eventual deregistration/destaging) of MSIX apps that have been set up by the tenant admin. This checks whether the component had any failures during package staging. Failures in staging will prevent some MSIX apps from working properly for the end user. If this check fails, it is non fatal and the machine still can service connections, main issue may be certain apps will not work for end-users. (Currently Enabled)
        type: string
        description: Represents the name of the health check operation performed.
        readOnly: true
      healthCheckResult:
        enum:
        - Unknown
        - HealthCheckSucceeded
        - HealthCheckFailed
        - SessionHostShutdown
        x-ms-enum:
          name: HealthCheckResult
          modelAsString: true
          values:
          - value: Unknown
            description: Health check result is not currently known.
          - value: HealthCheckSucceeded
            description: Health check passed.
          - value: HealthCheckFailed
            description: Health check failed.
          - value: SessionHostShutdown
            description: We received a Shutdown notification.
        type: string
        description: Represents the Health state of the health check we performed.
        readOnly: true
      additionalFailureDetails:
        $ref: '#/definitions/SessionHostHealthCheckFailureDetails'
        description: Additional detailed information on the failure.
        readOnly: true
  SessionHostHealthCheckFailureDetails:
    type: object
    description: Contains details on the failure.
    properties:
      message:
        type: string
        description: 'Failure message: hints on what is wrong and how to recover.'
        readOnly: true
      errorCode:
        type: integer
        format: int32
        description: Error code corresponding for the failure.
        readOnly: true
      lastHealthCheckDateTime:
        format: date-time
        type: string
        description: The timestamp of the last update.
        readOnly: true
  SessionHostList:
    type: object
    title: SessionHostList
    description: List of SessionHost definitions.
    properties:
      value:
        type: array
        description: List of SessionHost definitions.
        items:
          $ref: '#/definitions/SessionHost'
      nextLink:
        type: string
        readOnly: true
        description: Link to the next page of results.
  CloudError:
    description: Cloud error object.
    type: object
    x-ms-external: true
    properties:
      error:
        $ref: '#/definitions/CloudErrorProperties'
  SessionHostPatch:
    type: object
    description: SessionHost properties that can be patched.
    allOf:
    - $ref: ../../../../../common-types/resource-management/v1/types.json#/definitions/Resource
    properties:
      properties:
        description: Detailed properties for SessionHost
        x-ms-client-flatten: true
        $ref: '#/definitions/SessionHostPatchProperties'
  CloudErrorProperties:
    description: Cloud error object properties.
    type: object
    properties:
      code:
        description: Error code
        type: string
      message:
        description: Error message indicating why the operation failed.
        type: string
parameters:
  SessionHostNameParameter:
    name: sessionHostName
    in: path
    required: true
    type: string
    description: The name of the session host within the specified host pool
    maxLength: 48
    minLength: 3
    x-ms-parameter-location: method
  HostPoolNameParameter:
    name: hostPoolName
    in: path
    required: true
    type: string
    description: The name of the host pool within the specified resource group
    maxLength: 64
    minLength: 3
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'