Overview
Hydra has a limited set of REST web API calls to manage session hosts, scripts, and images.
To enable this feature, create a new secret in the Key Vault deployed with Hydra (you have to give yourself access to the secrets of the Key Vault first).
| Name | Secret value |
|---|
| Hydra-RESTAccess | A complex (URL encoded) self-defined secret with at least 32 characters. Make this complex to secure access. |
If the secret doesn’t exist, is empty, or has fewer than 32 characters, Hydra will not accept REST calls.
After creating or changing the secret, a restart of Hydra (the app service) is necessary. Do this only if no imaging or deployment is currently running. You can restart Hydra by:
-
Clicking on the Avatar menu (upper-right corner).
-
Selecting Restart Engine.
Authorization
Hydra REST API uses the Authorization header for authentication.
| Header | Value |
|---|
| Authorization | "SharedKey " |
Available Endpoints
Create a new host
| Endpoint | Request body | Response |
|---|
POST /rest/hostpools/<HostPool-Guid>/addhostspartial | Can contain:
- VmSize: String; e.g., Standard_D8as_v5
- AssigneUser: String; e.g., user@domain.com (only for personal pools)
- DiskSizeInGb: Number; Size of the OS disk
- PoolGroup: string; custom, only valid if the host pool Guid is Guid.Empty (must match one of the pools with the deployment tag "AVD.PoolGroup"
- Other properties are used from the default deployment configuration of the host pool
| A GUID to query the state of the task. |
Delete a host with VM
| Endpoint | Request body | Response |
|---|
GET /rest/sessionhosts/<SessionHost-Guid>/delete | - | A GUID to query the state of the task. |
Change VM size and/or OS-disk size a host with VM
VM will be started and stopped.
| Endpoint | Request body | Response |
|---|
POST /rest/sessionhosts/<SessionHost-Guid>/resize | Can contain (one or both settings):
- VmSize: String; e.g. Standard_D8as_v5
- DiskSizeGb: Int; Size of the OS-Disk in GByte (increase only; the VM is also started to expand the partition)
| A GUID to query the state of the task. |
Get assigned session hosts for a user
| Endpoint | Request body | Response |
|---|
GET /rest/hostpools/<HostPool-Guid/users/<UPN>/sessionhosts | - | A list of session hosts where the user is assigned. If HostPool-Guid is a GUID. Empty, all assigned hosts in all pools are returned. |
Get available scripts for a user
| Endpoint | Request body | Response |
|---|
GET /rest/scripts | - | A list of scripts. |
Get available script collections
| Endpoint | Request body | Response |
|---|
GET /rest/scriptcollections | - | A list of script collections. |
Run a script or script collection on a host
| Endpoint | Request body | Response |
|---|
POST /rest/sessionhosts/<SessionHost-Guid>/scriptorscriptcollection | Should contain the ID of the script or collection as text. | A GUID to query the state of the task. |
Get the list of imaging definitions
| Endpoint | Request body | Response |
|---|
GET /rest/azure/imagingDefinitions | - | A list of ImagingDefinition. |
Save and run a imaging definition
| Endpoint | Request body | Response |
|---|
POST /rest/scenes/<SceneId>/StartStoredImageDefinition | <ImagingDefinition> | A GUID to query the state of the task. |
Get the state of tasks
| Endpoint | Request body | Response |
|---|
GET /rest/actions/<task-guid> | - |
- 200: Done successfully
- 404: Not found
- 202: Still running
- 409: Failed
|
Optional filtering
HTTP-Get commands to query VMs by user or to delete a host can have an additional filter in the header:
| Filter | Value | Description |
|---|
| "LimitToSubscriptions" | "49f90bf9-ddf8-48b2-bf90-629f3dbef550,f7f733a1-92f8-4ff4-8e49-6ecd7c3533f3" | Filters by subscriptions of the VMs/hosts. |
| "LimitToPoolGroups" | "engineering,sales" | Filters by pool groups. |
| "LimitToPoolType" | "personal" | Filters by host pool type: personal or pooled. |