Перейти к основному содержимому

13.5.10 Виртуальный рабочий стол

Методы​

desktop-create​

Метод создания виртуального рабочего стола, пример использования в глобальной инфраструктуре vStack HCP.

Указание root/Administrator необязательно, при не заполнении users будет создана учетная запись со случайным паролем.

При указании root/Administrator учётной записи список ssh_authorized_keys не должен быть пустым.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-create",
    "params": {
        "template_id": 2,
        "vspace_id": 5,
        "name": "My Virtual Desktop",
        "description": "Test VDI Desktop",
        "default_protocol_id": 1, // Optional
        "guest": {
            "hostname": "test.vstack.com",
            // Optional
            "users": {
                "root" {
                    "ssh_authorized_keys": [
                        "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBBG7C/OMiPHCh4Ct8ZXUZgJL3te4Stq3uH1nBYNgF3F test.test@itglobal.com"
                    ],
                    "password": "password"
                }
            }
        }
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "connections_active": 0,
            "connections_await": 0,
            "holder_provider": "local",
            "holder_username": "vdi-admin-test",
            "created_ts": 1737622888,
            "modified_ts": 1737622888,
            "creator_provider": "local",
            "creator_username": "god",
            "description": "Test VDI Desktop",
            "desktop_status": 10,
            "default_protocol_id": 1,
            "id": 106,
            "name": "My Virtual Desktop",
            "os_profile": 3062,
            "os_type": 7,
            "qpoints": 1,
            "vspace_id": 1
        }
    }
}

desktop-delete​

Метод удаления виртуального рабочего стола. При удалении рабочего стола в Manual vSpace VM не будет удалена, и будет вновь видна в списке VM для импорта.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-delete",
    "params": {
        "id": 25
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Desktop ID 25 deleted"
    }
}

desktop-connect​

Метод получения информации для подключения к удалённому рабочему столу.

Протокол выбирается автоматически при отсутствии параметра protocol_id. Параметры, влияющие на выбор протокола:

  • ПРИОРИТЕТ-1 Шаблон может иметь параметр default_protocol_id — значение id протокола по умолчанию для виртуальных столов, созданных из этого шаблона.

  • ПРИОРИТЕТ-2 Рабочее пространство может иметь параметр default_protocol_id — значение id протокола по умолчанию для виртуальных столов, созданных внутри пространства.

  • ПРИОРИТЕТ-3 Виртуальный стол может иметь параметр default_protocol_id — значение id протокола по умолчанию для этого виртуального стола.

INFO

Будет выбран протокол, значение которого содержится в параметре объекта с самым высоким приоритетом. Например, если для шаблона задан протокол по умолчанию с id=1, а в рамках рабочего пространства выбран протокол с id=2, то будет выбран протокол с id=2. Для изменения этих параметров используйте методы vspace-set и desktop-set. Наследуемый протокол по умолчанию из шаблона не может быть изменён для уже созданного виртуального стола.

Параметр client_os может быть указан для формирования корректного URL учитывая особенности подключения пользователя на разных ОС.

INFO

Например, при использовании протокола RDP на MacOS поле url в ответе метода будет преобразовано в читаемый формат для успешного запуска Windows App на системе пользователя.

Возможные значения client_os:

  • windows;
  • linux;
  • macos;
  • android;
  • ios.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-connect",
    "params": {
        // Параметр доступен всегда кроме коннекта из Floating vSpace (использовать vspace_id)
        "id": 25,
        // Опционально
        "protocol_id": 1,
        // Опционально
        "client_os": "macos",
        // Только если коннект происходит в рамках Floating vSpace
        "vspace_id": 123,
        // Использовать SSO аутентификацию (требуется агент на десктопе)
        "use_sso": true
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ с использованием SSO:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "ip": "10.78.24.25:3389",
            "url": "rdp://10.78.24.25:3389/?data=UkhSMQEYNi%2FIDmxE1x0ECrz2ljbYjZVDJ77OQrAPFAAAAAAAAAA6AAAAAAAAAEATtl52hanbgnmsrBI87RuSWsSUi0L17SXkruUiiDGbwa%2FLOUavOnaKryPQPpymUKMMjVaab%2FTyxYQHp%2FCfN8Uke4YW0xa%2FSDsgHZvjMIqTIg%3D%3D",
            "sso": {
                "username": "test",
                "password": "secret"
            },
            "protocol_id": 1,
            "desktop_id": 25
        }
    }
}

Успешный ответ для RDP:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "ip": "10.78.24.25:3389",
            "url": "rdp://10.78.24.25:3389",
            "protocol_id": 1,
            "desktop_id": 25
        }
    }
}

desktop-console​

Запрос wss до консоли VM.

При наличии существующего подключения оно прерывается.

В качестве параметров передаётся id (Virtual Desktop ID). Опциональный параметр type может использоваться для указания типа консоли (по умолчанию данный параметр имеет значение = 1; значение = 2 указывает на необходимость получения WSS до текстовой консоли).

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-console",
    "params": {
        "id": 143
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "id": 143,
            "wss": "wss://vdi.z.vstack.com/.api/ws/wsse9d7fd5d-c500-48ba-ac43-990fdf738bb7"
        }
    }
}

desktop-start, desktop-stop, desktop-restart​

Методы управления виртуальной машиной рабочего стола (desktop-stop и desktop-restart вызываются подобно примеру с desktop-start).

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-start",
    "params": {
        "id": 43
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Desktop ID 43 started"
    }
}

desktop-set​

Метод установки новых значений полей name, description и default_protocol_id для рабочего стола.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-set",
    "params": {
        "id": 43,
        "name": "test set", // Optional
        "default_protocol_id": 1, // Optional
        "description": "test set" // Optional
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Desktop ID 43 updated"
    }
}

desktop-get​

Метод получения информации об удалённом рабочем столе. При наличии у пользователя привилегии Extended Response (входит в роль VDI Infrastructure Owner) будет представлен более детализированный ответ.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-get",
    "params": {
        "id": 43
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ (с привилегией Extended Response):

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "connections_active": 0,
            "connections_await": 0,
            "holder_provider": "local",
            "holder_username": "vdi-admin-test",
            "address": "10.78.25.130",
            "created_ts": 1734102916,
            "modified_ts": 1737622888,
            "creator_provider": "local",
            "creator_username": "vdi-admin-test",
            "default_protocol_id": 1,
            "description": "Test VDI Desktop",
            "desktop_status": 10,
            "id": 43,
            "internal_addr": "0.10.0.13",
            "name": "My Virtual Desktop",
            "os_profile": 3062,
            "os_type": 7,
            "qpoints": 1,
            "vspace_id": 1,
            "protocols": [
                {
                    "additional_info": {},
                    "created_ts": 1740321088,
                    "default_port": 3389,
                    "id": 1,
                    "name": "rdp"
                },
                {
                    "additional_info": {},
                    "created_ts": 1740321088,
                    "default_port": 8554,
                    "id": 2,
                    "name": "loudplay"
                }
            ],
            "vm": {
                "GI_object": 1,
                "admin_status": 3,
                "boot_media_id": 0,
                "cpu_priority": 1,
                "cpus": 4,
                "create_completed": 1,
                "created": 1734102916,
                "description": "Virtual Machine created by vStack VDI for desktop ID 43",
                "disks": [
                    {
                        "guid": "16694160622249965510",
                        "iops_limit": null,
                        "label": null,
                        "mbps_limit": null,
                        "sector_size": {
                            "logical": 512,
                            "physical": 4096
                        },
                        "size": 19327352832,
                        "slot": 1
                    }
                ],
                "gc_id": 3,
                "gc_name": "Cloud-base",
                "guest": {
                    "ram_balloon_performed": 0,
                    "ram_balloon_requested": 0,
                    "ram_used": 4415889408
                },
                "hv_faults": {
                    "sigabort": {
                        "interval": 60,
                        "restarts": 5
                    }
                },
                "hw_version": 5,
                "id": 589738,
                "incarnation": 17341033413,
                "locked": 0,
                "modified": 1734103341,
                "name": "Virtual Desktop #43",
                "ndmp_address": "10.78.41.213",
                "network_ports": [
                    {
                        "address": "10.78.25.130",
                        "ip_guard": 1,
                        "mac": "fe:2b:f9:fe:bf:8f",
                        "network_id": 4,
                        "port_id": 46129,
                        "ratelimit_mbits": 0,
                        "slot": 1
                    }
                ],
                "node": 5,
                "oper_status": 3,
                "oper_status_ts": 1734103343,
                "os_profile": "3062",
                "os_type": 7,
                "pool": "1520539762154027016",
                "ram": 4294967296,
                "root_dataset": 8145728438537000623,
                "root_dataset_name": "z03/.vm_V4/000589738",
                "rstart": 0,
                "service": 0,
                "status": 3,
                "uefi": "/usr/local/share/uefi-firmware/vStack_BHYVE_UEFI_20210214.fd",
                "vcpu_class": 1,
                "vdc": 35
            }
        }
    }
}

Успешный ответ (БЕЗ привилегии Extended Response):

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "connections_active": 0,
            "connections_await": 0,
            "holder_provider": "local",
            "holder_username": "vdi-admin-test",
            "modified_ts": 1737622888,
            "created_ts": 1734102916,
            "creator_provider": "local",
            "creator_username": "vdi-admin-test",
            "description": "Test VDI Desktop",
            "desktop_status": 10,
            "id": 43,
            "name": "My Virtual Desktop",
            "os_profile": 3062,
            "os_type": 7,
            "qpoints": 1,
            "vspace_id": 1,
            "protocols": [
                {
                    "additional_info": {},
                    "created_ts": 1740321088,
                    "default_port": 3389,
                    "id": 1,
                    "name": "rdp"
                },
                {
                    "additional_info": {},
                    "created_ts": 1740321088,
                    "default_port": 8554,
                    "id": 2,
                    "name": "loudplay"
                }
            ],
            "vm": {
                "cpus": 4,
                "create_completed": 1,
                "created": 1734102916,
                "disks": [
                    {
                        "guid": "16694160622249965510",
                        "iops_limit": null,
                        "label": null,
                        "mbps_limit": null,
                        "sector_size": {
                            "logical": 512,
                            "physical": 4096
                        },
                        "size": 19327352832,
                        "slot": 1
                    }
                ],
                "guest": {
                    "ram_balloon_performed": 0,
                    "ram_balloon_requested": 0,
                    "ram_used": 4415889408
                },
                "id": 589738,
                "locked": 0,
                "oper_status": 3,
                "oper_status_ts": 1734103343,
                "ram": 4294967296
            }
        }
    }
}

desktop-list​

Метод получения информации об удалённых рабочих столах списком.

Опциональный параметр objective позволяет получить альтернативный вид списка, при его отсутствии отображается массив объектов.

Для отображения виртуальных столов в рамках одного рабочего пространства можно использовать параметр vspace_id.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-list",
    "params": {
        "objective": 1
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "100": {
                "connections_active": 0,
                "connections_await": 0,
                "holder_provider": "local",
                "holder_username": "vdi-admin-test",
                "created_ts": 1737456135,
                "modified_ts": 1737622888,
                "creator_provider": "local",
                "creator_username": "god",
                "default_protocol_id": null,
                "description": "sdadada",
                "desktop_status": 1,
                "id": 100,
                "name": "Desktop",
                "os_profile": 3062,
                "os_type": 7,
                "qpoints": 1,
                "vspace_id": 2
            },
            "101": {
                "connections_active": 0,
                "connections_await": 0,
                "holder_provider": "local",
                "holder_username": "vdi-admin-test",
                "created_ts": 1737469876,
                "modified_ts": 1737622888,
                "creator_provider": "local",
                "creator_username": "god",
                "default_protocol_id": 1,
                "description": "",
                "desktop_status": 3,
                "id": 101,
                "name": "ubuntu test upgrade desktop 22.04.4.v4",
                "os_profile": 4002,
                "os_type": 6,
                "qpoints": 1,
                "vspace_id": 1,
                "protocols": [
                    {
                        "additional_info": {},
                        "created_ts": 1740321088,
                        "default_port": 3389,
                        "id": 1,
                        "name": "rdp"
                    }
                ],
            },
            "102": {
                "connections_active": 0,
                "connections_await": 0,
                "holder_provider": "local",
                "holder_username": "vdi-admin-test",
                "created_ts": 1737470661,
                "modified_ts": 1737622888,
                "creator_provider": "local",
                "creator_username": "god",
                "description": "",
                "default_protocol_id": 1,
                "desktop_status": 3,
                "id": 102,
                "name": "ubuntu test upgrade desktop 22.04.4.v4 №2",
                "os_profile": 4002,
                "os_type": 6,
                "qpoints": 1,
                "vspace_id": 1,
                "protocols": [
                    {
                        "additional_info": {},
                        "created_ts": 1740321088,
                        "default_port": 3389,
                        "id": 1,
                        "name": "rdp"
                    },
                    {
                        "additional_info": {},
                        "created_ts": 1740321088,
                        "default_port": 8554,
                        "id": 2,
                        "name": "loudplay"
                    }
                ],
            },
            ...
        }
    }
}

desktop-template-create​

Метод создания (обновления) шаблонов настроек для создания VM удалённого рабочего стола. protocol_ids — необязательный параметр.

INFO

Если протокол уже поддерживается образом ОС, указанным в шаблоне, он автоматически копируется в шаблон, дублировать в protocol_ids не требуется.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-template-create",
    "params": {
        "id": 2, // ID шаблона (не VM), опционально,
                 // при занятом ID — шаблон будет перезаписан
        "name": "test.template.gi.q7", // Имя шаблона (не VM)
        "os_type": 7,
        "default_protocol_id": 1, // Опционально, протокол по умолчанию
        "os_profile": 3062,
        "template": {
            "ram": 4294967296,
            "cpus": 4,
            "cluster_selector": 2, // Опционально
            "cluster_id": "44a839bc-6b25-4b77-a277-1b749b617c79", // Опционально
            "disks": [
                {
                    "sector_size": { // Опционально
                        "logical": 512,
                        "physical": 4096
                    },
                    "label": "test.template.gi.q7", // Опционально
                    "size": 19327352832,
                    "slot": 1
                }
            ],
            "network_ports": [
                {
                    "ratelimit_mbits": 0 // Опционально
                }
            ],
            "guest": {
                "boot_cmds": [],
                "run_cmds": [],
                "resolver": {
                    "name_server": [
                        "8.8.8.8",
                        "8.8.4.4",
                        "1.1.1.1"
                    ],
                    "search": "nsa.gov"
                }
            },
            "vcpu_class": 1, // Опционально
            "boot_media": 1, // Опционально
            "pool_selector": "0",
            "protocol_ids": [2],
        }
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "id": 2
        },
        "message": "Created template ID 2"
    }
}

desktop-template-delete​

Метод удаления шаблона настроек для создания VM удалённого рабочего стола.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-template-delete",
    "params": {
        "id": 2,
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Deleted template ID 2"
    }
}

desktop-templates​

Метод для просмотра списка созданных шаблонов.

При указании objective возможен альтернативный вид списка.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-templates",
    "params": {
        "objective": 1
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "10": {
                "id": 10,
                "name": "ubuntu.22.01.2.gi.q7",
                "os_profile": 3010,
                "default_protocol_id": 1,
                "os_type": 6,
                "protocols": [
                        {
                            "additional_info": {},
                            "created_ts": 1740321088,
                            "default_port": 3389,
                            "id": 1,
                            "name": "rdp"
                        }
                ],
                "template": {
                    "cluster_id": "44a839bc-6b25-4b77-a277-1b749b617c79",
                    "cpus": 4,
                    "disks": [
                        {
                            "label": "ubuntu.22.0.4.gi.q7",
                            "sector_size": {
                                "logical": 512,
                                "physical": 4096
                            },
                            "size": 19327352832,
                            "slot": 1
                        }
                    ],
                    "guest": {
                        "boot_cmds": [
                            "sudo apt-get update"
                        ],
                        "resolver": {
                            "name_server": [
                                "8.8.8.8",
                                "8.8.4.4",
                                "1.1.1.1"
                            ],
                            "search": "nsa.gov"
                        },
                        "run_cmds": []
                    },
                    "network_ports": [
                        {
                            "ratelimit_mbits": 0
                        }
                    ],
                    "pool_selector": "0",
                    "ram": 4294967296,
                }
            },
            ...
        }
    }
}

desktop-statuses​

Метод получения словаря статусов виртуальных машин удалённых рабочих столов.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-statuses",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "1": "Offline",
            "10": "Created",
            "100": "Restoring",
            "101": "Restore failed",
            "11": "Suspended",
            "12": "Suspending",
            "13": "Suspend failed",
            "14": "Resuming",
            "15": "Resume failed",
            "16": "Create failed",
            "17": "Delete failed",
            "2": "Starting",
            "3": "Started",
            "4": "Start failed",
            "5": "Stopping",
            "6": "Stop failed",
            "7": "Creating",
            "8": "Deleting",
            "9": "Deleted"
        }
    }
}

desktop-boot_media-list​

Метод получения словаря Recovery media.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-boot_media-list",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ c использованием кластера как инфраструктуры:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "0": "none",
            "1": "FreeBSD 12.2-RELEASE",
            "10": "Veeam Recovery 5.0",
            "100": "Windaz test",
            "10000": "VeeamRecoveryMedia_syn_20241126",
            "101": "FreeBSD DeIaaS vStack",
            "11": "FreeBSD 14.0-RELEASE",
            "2": "SystemRescue CD 10.01",
            "24": "Ubuntu 24.04 Live server",
            "5": "System Rescue CD 9.04",
            "7": "pfSense 2.6.0 RELEASE"
        }
    }
}

Успешный ответ c использованием GI как инфраструктуры:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
             "44a839bc-6b25-4b77-a277-1b749b617c79": {
                "0": "none",
                "1": "FreeBSD 12.2-RELEASE",
                "100": "Windaz test",
                "2": "SystemRescue CD 10.01",
                "3": "FreeBSD 12.2-RELEASE",
                "4": "FreeBSD 13.0-RELEASE",
                "5": "FreeBSD 13.1-RELEASE"
            },
            "fefa5efe-73c9-11ed-8409-c38eafb91e77": {
                "0": "none",
                "1": "FreeBSD 12.2-RELEASE",
                "10": "Veeam Recovery 5.0",
                "100": "Windaz test",
                "10000": "VeeamRecoveryMedia_syn_20241126",
                "101": "FreeBSD DeIaaS vStack",
                "11": "FreeBSD 14.0-RELEASE",
                "2": "SystemRescue CD 10.01",
                "24": "Ubuntu 24.04 Live server",
                "5": "System Rescue CD 9.04",
                "7": "pfSense 2.6.0 RELEASE"
            }
        }
    }
}

desktop-profile-create​

Метод добавления конфигурации операционной системы HCP в поддерживаемые профили рабочих столов текущим VDI. protocol_ids необязательный параметр.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-profile-create",
    "params": {
        "os_type": 7,
        "os_profile": 3061,
        "protocol_ids": [1]
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Created"
    }
}

desktop-protocols​

Метод получения словаря поддерживаемых протоколов в VDI.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-protocols",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "1": {
                "additional_info": {},
                "created_ts": 1740321088,
                "default_port": 3389,
                "id": 1,
                "name": "rdp"
            },
            "2": {
                "additional_info": {},
                "created_ts": 1740321088,
                "default_port": 8854,
                "id": 2,
                "name": "loudplay"
            }
        }
    }
}

desktop-profile-delete​

Метод удаления конфигурации операционной системы рабочих столов.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-profile-delete",
    "params": {
        "os_type": 7,
        "os_profile": 3061
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "message": "Deleted"
    }
}

desktop-profiles​

Метод получения списка поддерживаемых образов операционной системы (os_type и os_profile).

При указании параметра all будет запрошен весь список поддерживаемых систем используемой инфрастуктуры, без фильтрации (рекомендуется использовать только как словарь к методу desktop-profile-create).

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-profiles",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ для варианта использования GI:

Поля clusters отображают наличие os_type и os_profile в инфраструктуре каждого кластера ГИ.

{
    "jsonrpc": "2.0",
    "id": "100197df-94c5-44b1-8e61-71f975944563",
    "result": {
        "code": 1,
        "data": {
            "6": {
                "clusters": [
                    "fefa5efe-73c9-11ed-8409-c38eafb91e77",
                    "44a839bc-6b25-4b77-a277-1b749b617c79"
                ],
                "id": 6,
                "name": "Linux",
                "profiles": [
                    {
                        "clusters": [
                            "fefa5efe-73c9-11ed-8409-c38eafb91e77",
                            "44a839bc-6b25-4b77-a277-1b749b617c79"
                        ],
                        "description": "Ubuntu 22.04.1 v1",
                        "id": 3010,
                        "min_size": 5034213376,
                        "name": "Ubuntu 22.04.1 v1",
                        "protocols": []
                    },
                    {
                        "clusters": [
                            "fefa5efe-73c9-11ed-8409-c38eafb91e77",
                            "44a839bc-6b25-4b77-a277-1b749b617c79"
                        ],
                        "description": "Ubuntu 22.04.4 v0",
                        "id": 4002,
                        "min_size": 5138022400,
                        "name": "Ubuntu 22.04.4 v0",
                        "protocols": []
                    }
                ]
            },
            "7": {
                "clusters": [
                    "fefa5efe-73c9-11ed-8409-c38eafb91e77",
                    "44a839bc-6b25-4b77-a277-1b749b617c79"
                ],
                "id": 7,
                "name": "Windows",
                "profiles": [
                    {
                        "clusters": [
                            "fefa5efe-73c9-11ed-8409-c38eafb91e77",
                            "44a839bc-6b25-4b77-a277-1b749b617c79"
                        ],
                        "description": "Windows Server 2022 v2",
                        "id": 3062,
                        "min_size": 19327352832,
                        "name": "Windows Server 2022 v2",
                        "protocols": [
                            {
                                "additional_info": {},
                                "created_ts": 1740321088,
                                "default_port": 3389,
                                "id": 1,
                                "name": "rdp"
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Успешный ответ для варианта использования кластера:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "7": {
                "id": 7,
                "name": "Windows",
                "profiles": [
                    {
                        "description": "Windows Server 2022 v2",
                        "id": 3062,
                        "min_size": 19327352832,
                        "name": "Windows Server 2022 v2",
                        "protocols": [
                            {
                                "additional_info": {},
                                "created_ts": 1740321088,
                                "default_port": 3389,
                                "id": 1,
                                "name": "rdp"
                            }
                        ]
                    }
                ]
            }
        }
    }
}

desktop-perfdata​

Запрос performance data. Возможные метрики (параметр metric):

  • cpu;
  • disk;
  • net;
  • ram;
  • all (всё вышеперечисленное).

Возможно указание отрезка времени в виде интервала от текущего момента, либо с явным указанием начала и конца отрезка времени.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-perfdata",
    "params": {
        "metric": "all",
        "desktop_id": 43,
        "interval": "3m",
        "slice": "1m"
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Запрос (явное указание начала и конца отрезка времени):

{
    "jsonrpc": "2.0",
    "method": "desktop-perfdata",
    "params": {
        "metric": "all",
        "desktop_id": 43,
        "begin_time": 1669024800,
		"end_time":	1669025400,
        "slice": "1m"
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "results": [
                {
                    "series": [
                        {
                            "columns": [
                                "time",
                                "cpu",
                                "vm_cpus"
                            ],
                            "name": "bhyve_cpu",
                            "values": [
                                [
                                    1735315020,
                                    0,
                                    4
                                ],
                                [
                                    1735315080,
                                    0,
                                    4
                                ],
                                [
                                    1735315140,
                                    0,
                                    4
                                ],
                                [
                                    1735315200,
                                    0,
                                    4
                                ]
                            ]
                        }
                    ],
                    "statement_id": 0
                },
                {
                    "series": [
                        {
                            "columns": [
                                "time",
                                "read_bytes",
                                "write_bytes",
                                "read_iops",
                                "write_iops"
                            ],
                            "name": "virtio_blk",
                            "tags": {
                                "slot": "1"
                            },
                            "values": [
                                [
                                    1735315020,
                                    0,
                                    4505.6,
                                    0,
                                    0.422222222220929
                                ],
                                [
                                    1735315080,
                                    0,
                                    4391.82222220103,
                                    0,
                                    0.416666666666667
                                ],
                                [
                                    1735315140,
                                    0,
                                    1388.08888893127,
                                    0,
                                    0.258333333333333
                                ],
                                [
                                    1735315200,
                                    0,
                                    1268.62222220103,
                                    0,
                                    0.244444444445738
                                ]
                            ]
                        }
                    ],
                    "statement_id": 1
                },
                {
                    "series": [
                        {
                            "columns": [
                                "time",
                                "rx_bytes",
                                "tx_bytes",
                                "rx_pps",
                                "tx_pps"
                            ],
                            "name": "virtio_net",
                            "tags": {
                                "slot": "1"
                            },
                            "values": [
                                [
                                    1735315020,
                                    660.44444445769,
                                    7.5,
                                    7.58333333333333,
                                    0.138888888885655
                                ],
                                [
                                    1735315080,
                                    798.888888875643,
                                    1.5,
                                    7.75,
                                    0.0277777777810115
                                ],
                                [
                                    1735315140,
                                    771.44444445769,
                                    0,
                                    7.27777777779071,
                                    0
                                ],
                                [
                                    1735315200,
                                    650.722222208977,
                                    0,
                                    6.13888888887595,
                                    0
                                ]
                            ]
                        }
                    ],
                    "statement_id": 2
                },
                {
                    "series": [
                        {
                            "columns": [
                                "time",
                                "guest_mem",
                                "VM_mem",
                                "hv_mem"
                            ],
                            "name": "bhyve_cpu",
                            "values": [
                                [
                                    1735315020,
                                    4210413568,
                                    4415889408,
                                    4307505152
                                ],
                                [
                                    1735315080,
                                    4210413568,
                                    4415889408,
                                    4307505152
                                ],
                                [
                                    1735315140,
                                    4210413568,
                                    4415889408,
                                    4307505152
                                ],
                                [
                                    1735315200,
                                    4210413568,
                                    4415889408,
                                    4307505152
                                ]
                            ]
                        }
                    ],
                    "statement_id": 3
                }
            ]
        }
    }
}

desktop-roles​

Метод отображения списка пользователей и групп Active Directory, которые имеют доступ к данному рабочему столу исходя из их области видимости ролей.

При указании objective возможен альтернативный вид списка.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-roles",
    "params": {
        "id": 1
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "groups": [
                {
                    "group_id": "612c02c3-5f8f-4d2b-847e-6d2af7184ff3",
                    "roles": [
                        {
                            "attrs": {},
                            "id": 1,
                            "granted_ts": 1744213700,
                            "name": "VDI Master"
                        }
                    ]
                }
            ],
            "users": [
                {
                    "provider": "local",
                    "roles": [
                        {
                            "attrs": {},
                            "id": 1,
                            "granted_ts": 1744213700,
                            "name": "VDI Master"
                        },
                        {
                            "attrs": {},
                            "created_ts": 1744213890,
                            "creator_provider": "local",
                            "creator_username": "test_user",
                            "id": 10000,
                            "modified_ts": 1744215225,
                            "granted_ts": 1744213700,
                            "name": "Custom Role",
                            "username": "test_user"
                        }
                    ],
                    "username": "test_user"
                },
            ]
        }
    }
}

С objective:

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-privileges",
    "params": {
        "id": 1,
        "objective": 1
    },
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
    "result": {
        "code": 1,
        "data": {
            "groups": {
                "612c02c3-5f8f-4d2b-847e-6d2af7184ff3": [
                    {
                        "attrs": {},
                        "id": 1,
                        "granted_ts": 1744213700,
                        "name": "VDI Master"
                    }
                ]
            },
            "users": {
                "local": {
                    "test_user": [
                        {
                            "attrs": {},
                            "id": 1,
                            "granted_ts": 1744213700,
                            "name": "VDI Master"
                        }
                    ]
                }
            }
        }
    }
}

desktop-sessions​

Метод для получения списка сессий виртуальных рабочих столов.

При указании параметра objective возвращается альтернативный вид списка (объект с ключами по id сессий).

При указании параметров vspace_id, desktop_id, only_active, show_last, client_username и client_provider возвращаются только сессии, соответствующие указанным значениям. Все параметры опциональны.

Есть возможность указать временной отрезок для фильтрации сессий с помощью ts_start и ts_finish.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-sessions",
    "params": {
        "vspace_id": 1,
        "desktop_id": 143,
        "client_username": "god",
        "client_provider": "local",
        "show_last": 1, // Default 10
        "ts_start": 1747042543,
        "ts_finish": 1747042780,
        "only_active": true
    },
    "id": "09cb4028-bae4-4505-b5e7-f72a2893ebda"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "09cb4028-bae4-4505-b5e7-f72a2893ebda",
    "result": {
        "code": 1,
        "data": [
            {
                "bytes_received": 0,
                "bytes_sent": 0,
                "client_ip": "10.78.17.60",
                "client_provider": "local",
                "client_username": "god",
                "desktop_id": 143,
                "desktop_ip": "10.78.25.235",
                "desktop_port": 3389,
                "end_time": 1747042780,
                "id": 8,
                "last_activity": 1745227632,
                "local_port": 7878,
                "start_time": 1747042543,
                "status": 2,
                "vspace_id": 1
            }
        ]
    }
}

C objective:

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-sessions",
    "params": {
        "vspace_id": 1,
        "desktop_id": 143,
        "client_username": "god",
        "client_provider": "local",
        "objective": 1
    },
    "id": "09cb4028-bae4-4505-b5e7-f72a2893ebda"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "09cb4028-bae4-4505-b5e7-f72a2893ebda",
    "result": {
        "code": 1,
        "data": {
            "8": {
                "bytes_received": 0,
                "bytes_sent": 0,
                "client_ip": "10.78.17.60",
                "client_provider": "local",
                "client_username": "god",
                "desktop_id": 143,
                "desktop_ip": "10.78.25.235",
                "desktop_port": 3389,
                "end_time": null,
                "id": 8,
                "last_activity": 1745227632,
                "local_port": 7878,
                "start_time": 1745227632,
                "status": 1,
                "vspace_id": 1
            },
            "9": {
                "bytes_received": 0,
                "bytes_sent": 0,
                "client_ip": "10.78.17.60",
                "client_provider": "local",
                "client_username": "god",
                "desktop_id": 143,
                "desktop_ip": "10.78.25.235",
                "desktop_port": 3389,
                "end_time": null,
                "id": 9,
                "last_activity": 1745227731,
                "local_port": 7878,
                "start_time": 1745227731,
                "status": 1,
                "vspace_id": 1
            }
        }
    }
}

desktop-session-statuses​

Метод для получения списка статусов сессий виртуальных рабочих столов.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-session-statuses",
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153",
    "result": {
        "code": 1,
        "data": {
            "1": "Active",
            "2": "Completed"
        }
    }
}

desktop-session-abort​

Метод предназначен для принудительного завершения пользовательской сессии доставки удалённого рабочего стола (например, RDP и другие). Не относится к API-сессиям.

id — идентификатор сессии.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-session-abort",
    "params": {
        "id": 567
    },
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153",
    "result": {
        "code": 1,
        "message": "Completed"
    }
}

desktop-import-area-list​

Метод получения списка виртуальных машин в инфраструктуре, которые находятся в области видимости используемого vdc.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-import-area-list",
    "params": {},
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153",
    "result": {
        "code": 1,
        "data": [
            {
                "address": "10.78.25.224",
                "admin_status": 1,
                "cpu_count": 2,
                "create_completed": 1,
                "hcp_gi_cluster_id": "44a839bc-6b25-4b77-a277-1b749b617c79",
                "hw_version": 5,
                "locked": 0,
                "memory_count": 4294967296,
                "oper_status": 1,
                "oper_status_ts": 1756666227,
                "os_profile": 1023,
                "os_type": 6,
                "storage_provisioned": 21474836480,
                "vcpu_class": 1,
                "vdc_id": 35,
                "vm_id": 698629,
                "vm_name": "Agent Releases Host",
                "vm_status": 1
            },
            {
                "address": "10.78.25.87",
                "admin_status": 1,
                "cpu_count": 4,
                "create_completed": 1,
                "hcp_gi_cluster_id": "44a839bc-6b25-4b77-a277-1b749b617c79",
                "hw_version": 5,
                "locked": 0,
                "memory_count": 8589934592,
                "oper_status": 1,
                "oper_status_ts": 1750234178,
                "os_profile": 3023,
                "os_type": 6,
                "storage_provisioned": 34359738368,
                "vcpu_class": 1,
                "vdc_id": 35,
                "vm_id": 582312,
                "vm_name": "loudplay license server",
                "vm_status": 1
            }
        ]
    }
}

desktop-import​

Метод для импорта виртуальной машины из инфраструктуры в экземпляр виртуального стола.

Запрос:

{
    "jsonrpc": "2.0",
    "method": "desktop-import",
    "params": {
        "vm_id": 714768,
        "cluster_id": "44a839bc-6b25-4b77-a277-1b749b617c79", // Optional (только для GI)
        "vspace_id": 9339, // Только для 'manual' vSpace
        "protocols": [1],
        "default_protocol_id": 1 // Optional
    },
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153"
}

Успешный ответ:

{
    "jsonrpc": "2.0",
    "id": "a440a390-5d90-479f-aa4d-2e4c4398d153",
    "result": {
        "code": 1,
        "data": {
            "created_ts": 1757061871,
            "creator_provider": "local",
            "creator_username": "god",
            "default_protocol_id": 1,
            "description": "dsada",
            "desktop_status": 10,
            "id": 6669,
            "modified_ts": 1757061871,
            "name": "import",
            "os_profile": 3061,
            "os_type": 7,
            "protocols": [],
            "qpoints": 6,
            "vspace_id": 9339
        }
    }
}