Microsoft Azure Rendering Session API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Rendering Session API
schemes:
- https
tags:
- name: Rendering Session
paths:
  /accounts/{account_id}/sessions/{session_id}:
    put:
      operationId: microsoftAzureRemoterenderingCreatesession
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/api_version'
      - $ref: '#/parameters/account_id'
      - $ref: '#/parameters/session_id'
      - description: Settings of the session to be created.
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/create_session_settings'
      x-ms-examples:
        Create a rendering session:
          $ref: ./examples/CreateSession.json
      responses:
        '200':
          description: OK. Indicates that there was already a session with the same settings present. This is expected when session creation is retried.
          schema:
            $ref: '#/definitions/session_properties'
        '201':
          description: Created. The session was created successfully.
          schema:
            $ref: '#/definitions/session_properties'
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '400':
          description: Bad Request. Returned error object describes which issues occurred.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '409':
          description: Conflict. A rendering session with the ID already exists for the remote rendering account.
          x-ms-error-response: true
          schema:
            $ref: '#/definitions/error_response'
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Creates A New Rendering Session
      description: Needs a more full description created.
    get:
      operationId: microsoftAzureRemoterenderingGetsession
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/api_version'
      - $ref: '#/parameters/account_id'
      - $ref: '#/parameters/session_id'
      x-ms-examples:
        Get a previously created session by ID:
          $ref: ./examples/GetSession.json
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/session_properties'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Gets The Properties Of A Particular Rendering Session
      description: Needs a more full description created.
    patch:
      operationId: microsoftAzureRemoterenderingUpdatesession
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/api_version'
      - $ref: '#/parameters/account_id'
      - $ref: '#/parameters/session_id'
      - description: Settings used to update the session.
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/update_session_settings'
      x-ms-examples:
        Update a session:
          $ref: ./examples/UpdateSession.json
      responses:
        '200':
          description: OK. Session has been updated.
          schema:
            $ref: '#/definitions/session_properties'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '422':
          description: Unprocessable Entity. The maxLeaseTimeMinutes value was invalid. It has to be bigger than the current value of maxLeaseTimeMinutes.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Updates The Max Lease Time Of A Particular Rendering Session
      description: Needs a more full description created.
  /accounts/{account_id}/sessions/{session_id}/:stop:
    post:
      operationId: microsoftAzureRemoterenderingStopsession
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/api_version'
      - $ref: '#/parameters/account_id'
      - $ref: '#/parameters/session_id'
      x-ms-examples:
        Stop a session:
          $ref: ./examples/StopSession.json
      responses:
        '204':
          description: NoContent. Stop request was successful. The rendering session is stopped.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '404':
          description: Not found. No session with the provided session ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Stops A Particular Rendering Session
      description: Needs a more full description created.
  /accounts/{account_id}/sessions:
    get:
      operationId: microsoftAzureRemoterenderingListsessions
      produces:
      - application/json
      x-ms-pageable:
        itemName: sessions
        nextLinkName: '@nextLink'
      parameters:
      - $ref: '#/parameters/api_version'
      - $ref: '#/parameters/account_id'
      x-ms-examples:
        List sessions:
          $ref: ./examples/ListSessions.json
      responses:
        '200':
          description: OK. Returns the list of sessions which are in a 'Starting' or 'Ready' state.
          schema:
            $ref: '#/definitions/sessions_list'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              type: string
          schema:
            $ref: '#/definitions/error_response'
      tags:
      - Rendering Session
      summary: Microsoft Azure Gets A List Of All Rendering Sessions
      description: Needs a more full description created.
definitions:
  sessions_list:
    description: The result of a list sessions request.
    type: object
    properties:
      sessions:
        type: array
        description: The list of rendering sessions. Does not include sessions in 'Stopped' state.
        items:
          $ref: '#/definitions/session_properties'
      '@nextLink':
        description: If more rendering sessions are available this field will contain a URL where the next batch of sessions can be requested. This URL will need the same authentication as all calls to the Azure Remote Rendering API.
        type: string
        readOnly: true
    required:
    - sessions
  error_response:
    description: The error response containing details of why the request failed.
    properties:
      error:
        description: The error object containing details of why the request failed.
        type: object
        $ref: '#/definitions/error'
    type: object
    required:
    - error
  update_session_settings:
    description: Settings used to update the session.
    type: object
    properties:
      maxLeaseTimeMinutes:
        description: Update to the time the session will run after it reached the 'Ready' state. It has to be larger than the current value of maxLeaseTimeMinutes and less than 1440.
        example: 72
        type: integer
    required:
    - maxLeaseTimeMinutes
  session_properties:
    description: The properties of a rendering session.
    properties:
      id:
        example: contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28
        type: string
        description: The ID of the session supplied when the session was created.
      arrInspectorPort:
        example: 50052
        maximum: 65534
        minimum: 49152
        type: integer
        description: The TCP port at which the Azure Remote Rendering Inspector tool is hosted.
        readOnly: true
      handshakePort:
        example: 50051
        maximum: 65534
        minimum: 49152
        type: integer
        description: The TCP port used for the handshake when establishing a connection.
        readOnly: true
      elapsedTimeMinutes:
        description: Amount of time in minutes the session is or was in the 'Ready' state. Time is rounded down to a full minute.
        example: 10
        type: integer
        readOnly: true
      hostname:
        example: d4cefb7b-10b9-4631-934d-67445ffa9126.remoterenderingvm.westus2.mixedreality.azure.com
        type: string
        description: The hostname under which the rendering session is reachable.
        readOnly: true
      maxLeaseTimeMinutes:
        type: integer
        description: The time in minutes the session will run after reaching the 'Ready' state.
        example: 60
        readOnly: true
      size:
        $ref: '#/definitions/session_size'
        example: Standard
      status:
        $ref: '#/definitions/session_status'
        example: Ready
      teraflops:
        example: 10.6
        format: float
        type: number
        description: The computational power of the rendering session GPU measured in teraflops.
        readOnly: true
      error:
        x-nullable: true
        description: The error object containing details about the rendering session startup failure.
        type: object
        $ref: '#/definitions/error'
        example: null
        readOnly: true
      creationTime:
        type: string
        format: date-time
        description: The time when the rendering session was created. Date and time in ISO 8601 format.
        readOnly: true
    type: object
    required:
    - id
    - size
    - status
  session_status:
    enum:
    - Error
    - Expired
    - Starting
    - Ready
    - Stopped
    x-ms-enum:
      name: session_status
      modelAsString: true
      values:
      - value: Error
        description: The rendering session has encountered an error, and is unusable. This is a terminal state.
      - value: Expired
        description: The rendering session enters the 'Expired' state when it has been in the 'Ready' state longer than its lease time. This is a terminal state.
      - value: Starting
        description: The rendering session is starting, but not accepting incoming connections yet.
      - value: Ready
        description: The rendering session is ready for incoming connections.
      - value: Stopped
        description: The rendering session has been stopped with the 'Stop Session' operation. This is a terminal state.
    type: string
    example: Ready
    description: The status of the rendering session. Terminal states are 'Error', 'Expired', and 'Stopped'.
  create_session_settings:
    description: Settings of the session to be created.
    properties:
      maxLeaseTimeMinutes:
        example: 60
        type: integer
        description: The time in minutes the session will run after reaching the 'Ready' state. It has to be between 0 and 1440.
      size:
        $ref: '#/definitions/session_size'
    type: object
    required:
    - maxLeaseTimeMinutes
    - size
  error:
    description: The error object containing details of why the request failed.
    properties:
      code:
        type: string
        description: Error code.
      message:
        type: string
        description: A human-readable representation of the error.
      details:
        type: array
        items:
          $ref: '#/definitions/error'
        description: An array of details about specific errors that led to this reported error.
        readOnly: true
      target:
        description: The target of the particular error (e.g., the name of the property in error).
        type: string
        readOnly: true
      innerError:
        type: object
        $ref: '#/definitions/error'
        description: An object containing more specific information than the current object about the error.
        readOnly: true
    type: object
    required:
    - code
    - message
  session_size:
    enum:
    - Standard
    - Premium
    x-ms-enum:
      name: session_size
      modelAsString: true
      values:
      - value: Standard
        description: Standard rendering session size.
      - value: Premium
        description: Premium rendering session size.
    example: Standard
    type: string
    description: The size of the server used for the rendering session. The size impacts the number of polygons the server can render. Refer to https://docs.microsoft.com/azure/remote-rendering/reference/vm-sizes for details.
parameters:
  api_version:
    name: api-version
    in: query
    description: The API version to be used with the HTTP request.
    required: true
    type: string
    x-example: 2021-01-01-preview
    x-ms-parameter-location: method
  account_id:
    name: account_id
    description: The Azure Remote Rendering account ID.
    format: uuid
    in: path
    required: true
    type: string
    x-example: 30ea64bd-100f-4bf0-adc9-29fa45d4880c
    x-ms-parameter-location: method
  session_id:
    name: session_id
    description: An ID uniquely identifying the rendering session for the given account. The ID is case sensitive, can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 256 characters.
    in: path
    required: true
    type: string
    x-example: contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'