Share via

Remote Rendering - Create Session

  • Reference
Service:
Mixed Reality
API Version:
2021-01-01

Creates a new rendering session.

PUT {endpoint}/accounts/{account_id}/sessions/{session_id}?api-version=2021-01-01

URI Parameters

Name In Required Type Description
account_id
 path True

string

uuid

The Azure Remote Rendering account ID.
endpoint
 path True

string

The endpoint to use e.g. https://remoterendering.eastus.mixedreality.azure.com. A list can be found at https://docs.microsoft.com/azure/remote-rendering/reference/regions.
session_id
 path True

string

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.
api-version
 query True

string

The API version to be used with the HTTP request.

Request Header

Name Required Type Description
Authorization True

string

A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.

Request Body

Name Required Type Description
maxLeaseTimeMinutes True

integer

The time in minutes the session will run after reaching the 'Ready' state. It has to be between 0 and 1440.
size True

session_size

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.

Responses

Name Type Description
200 OK

session_properties

OK. Indicates that there was already a session with the same settings present. This is expected when session creation is retried.
201 Created

session_properties

Created. The session was created successfully.

Headers

MS-CV: string
400 Bad Request

error_response

Bad Request. Returned error object describes which issues occurred.

Headers

MS-CV: string
401 Unauthorized

Unauthorized. Missing or invalid authorization.

Headers

  • MS-CV: string
  • WWW-Authenticate: string
403 Forbidden

Forbidden. Authorization insufficient for given resource.

Headers

MS-CV: string
429 Too Many Requests

Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.

Headers

  • MS-CV: string
  • Retry-After: integer
500 Internal Server Error

error_response

Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.

Headers

MS-CV: string
Other Status Codes

error_response

Conflict. A rendering session with the ID already exists for the remote rendering account.

Security

Authorization

A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.

Type: apiKey
In: header

Examples

Create a rendering session

Sample request

PUT https://remoterendering.eastus.mixedreality.azure.com/accounts/30ea64bd-100f-4bf0-adc9-29fa45d4880c/sessions/contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28?api-version=2021-01-01

{
  "maxLeaseTimeMinutes": 60,
  "size": "Standard"
}

Sample response

Status code:
201 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "id": "contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28",
  "creationTime": "2020-11-11T11:11:11.111Z",
  "maxLeaseTimeMinutes": 60,
  "size": "Standard",
  "status": "Starting",
  "error": null
}
Status code:
200 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "id": "contoso-session-c2b8ac1d-9494-4852-a59c-8c28813adc28",
  "creationTime": "2020-11-11T11:11:11.111Z",
  "maxLeaseTimeMinutes": 60,
  "size": "Standard",
  "status": "Starting",
  "error": null
}
Status code:
400 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "BadRequest",
    "message": "The request was malformed."
  }
}
Status code:
409 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "Conflict",
    "message": "A resource already exists under the given ID."
  }
}
Status code:
401 
WWW-Authenticate: Bearer error="invalid_token"
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
403 
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
429 
Retry-After: 15
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
500 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "InternalServerError",
    "message": "An internal server error occurred."
  }
}

Definitions

Name Description
create_session_settings

Settings of the session to be created.
error

The error object containing details of why the request failed.
error_response

The error response containing details of why the request failed.
session_properties

The properties of a rendering session.
session_size

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

The status of the rendering session. Terminal states are 'Error', 'Expired', and 'Stopped'.

create_session_settings

Settings of the session to be created.

Name Type Description
maxLeaseTimeMinutes

integer

The time in minutes the session will run after reaching the 'Ready' state. It has to be between 0 and 1440.
size

session_size

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.

error

The error object containing details of why the request failed.

Name Type Description
code

string

Error code.
details

error[]

An array of details about specific errors that led to this reported error.
innerError

error

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
target

string

The target of the particular error (e.g., the name of the property in error).

error_response

The error response containing details of why the request failed.

Name Type Description
error

error

The error object containing details of why the request failed.

session_properties

The properties of a rendering session.

Name Type Description
arrInspectorPort

integer

The TCP port at which the Azure Remote Rendering Inspector tool is hosted.
creationTime

string

The time when the rendering session was created. Date and time in ISO 8601 format.
elapsedTimeMinutes

integer

Amount of time in minutes the session is or was in the 'Ready' state. Time is rounded down to a full minute.
error

error

The error object containing details about the rendering session startup failure.
handshakePort

integer

The TCP port used for the handshake when establishing a connection.
hostname

string

The hostname under which the rendering session is reachable.
id

string

The ID of the session supplied when the session was created.
maxLeaseTimeMinutes

integer

The time in minutes the session will run after reaching the 'Ready' state.
size

session_size

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

session_status

The status of the rendering session. Terminal states are 'Error', 'Expired', and 'Stopped'.
teraflops

number

The computational power of the rendering session GPU measured in teraflops.

session_size

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.

Name Type Description
Premium

string

Premium rendering session size.
Standard

string

Standard rendering session size.

session_status

The status of the rendering session. Terminal states are 'Error', 'Expired', and 'Stopped'.

Name Type Description
Error

string

The rendering session has encountered an error, and is unusable. This is a terminal state.
Expired

string

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

string

The rendering session is ready for incoming connections.
Starting

string

The rendering session is starting, but not accepting incoming connections yet.
Stopped

string

The rendering session has been stopped with the 'Stop Session' operation. This is a terminal state.