Microsoft Azure SessionHost API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Session Host API
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: '#/components/parameters/HostPoolNameParameter'
      - $ref: '#/components/parameters/SessionHostNameParameter'
      responses:
        '200':
          description: Successfully retrieved session host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionHost'
        default:
          description: Automation error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/HostPoolNameParameter'
      - $ref: '#/components/parameters/SessionHostNameParameter'
      - name: force
        in: query
        required: false
        description: Force flag to force sessionHost deletion even when userSession exists.
        schema:
          type: boolean
      responses:
        '200':
          description: Successfully removed session host.
        '204':
          description: Session host does not exist.
        default:
          description: Automation error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/HostPoolNameParameter'
      - $ref: '#/components/parameters/SessionHostNameParameter'
      - name: force
        in: query
        required: false
        description: Force flag to update assign, unassign or reassign personal desktop.
        schema:
          type: boolean
      responses:
        '200':
          description: Successfully updated session host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionHost'
        default:
          description: Automation error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      summary: Microsoft Azure Patch Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionHostPatch'
        description: Object containing SessionHost definitions.
  ? /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: '#/components/parameters/HostPoolNameParameter'
      - name: pageSize
        in: query
        required: false
        description: Number of items per page.
        schema:
          type: integer
          format: int32
      - name: isDescending
        in: query
        required: false
        description: Indicates whether the collection is descending.
        schema:
          type: boolean
      - name: initialSkip
        in: query
        required: false
        description: Initial number of items to skip.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successfully retrieved session hosts in host pool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionHostList'
        default:
          description: Automation error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/HostPoolNameParameter'
      - $ref: '#/components/parameters/SessionHostNameParameter'
      responses:
        '200':
          description: Successfully started provisioning retry on the sessionHost.
        default:
          description: Automation error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      summary: Microsoft Azure Post Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Desktopvirtualization Hostpools Hostpoolname Sessionhosts Sessionhostname Retryprovisioning
components:
  schemas:
    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
    CloudError:
      description: Cloud error object.
      type: object
      x-ms-external: true
      properties:
        error:
          $ref: '#/components/schemas/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: '#/components/schemas/SessionHostPatchProperties'
    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: '#/components/schemas/SessionHost'
        nextLink:
          type: string
          readOnly: true
          description: Link to the next page of results.
    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: '#/components/schemas/SessionHostHealthCheckFailureDetails'
          description: Additional detailed information on the failure.
          readOnly: true
    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
    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: '#/components/schemas/SessionHostProperties'
    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: '#/components/schemas/SessionHostHealthCheckReport'
  parameters:
    HostPoolNameParameter:
      name: hostPoolName
      in: path
      required: true
      description: The name of the host pool within the specified resource group
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 64
        minLength: 3
    SessionHostNameParameter:
      name: sessionHostName
      in: path
      required: true
      description: The name of the session host within the specified host pool
      x-ms-parameter-location: method
      schema:
        type: string
        maxLength: 48
        minLength: 3
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'