DocsKnowledge BaseAPI Explorer
Documentation›Explore more›ZStack ZSphere›API ReferenceZVF
Document navigation

SetVmUsbRedirect

API Request

URLs
PUT zstack/v1/vm-instances/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setVmUsbRedirect": {
    "enable": true
  },
  "systemTags": [],
  "userTags": []
}
Note:

The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.

Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"setVmUsbRedirect":{"enable":true}}' \
http://localhost:8080/zstack/v1/vm-instances/ceeca8ab8c6b33fab9bdc143dec13211/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.1
enable boolean body(contained in setVmUsbRedirect structure) Set to true to enable the switch, set to false to disable the switch
  • true
  • false
 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

On success, this API returns an empty JSON structure {}. On error, the returned JSON structure contains an error field, for example:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Examples

Java SDK
SetVmUsbRedirectAction action = new SetVmUsbRedirectAction();
action.uuid = "ceeca8ab8c6b33fab9bdc143dec13211";
action.enable = true;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SetVmUsbRedirectAction.Result res = action.call();
Python SDK
SetVmUsbRedirectAction action = SetVmUsbRedirectAction()
action.uuid = "ceeca8ab8c6b33fab9bdc143dec13211"
action.enable = true
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
SetVmUsbRedirectAction.Result res = action.call()

AttachUsbDeviceToVm

API Request

URLs
POST zstack/v1/usb-device/usb-devices/{usbDeviceUuid}/attach
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "vmInstanceUuid": "2a3697245a4a3e829a246e222c243688",
    "attachType": "PassThrough"
  },
  "systemTags": [],
  "userTags": []
}
Note: The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"vmInstanceUuid":"2a3697245a4a3e829a246e222c243688","attachType":"PassThrough"}}' http://localhost:8080/zstack/v1/usb-device/usb-devices/84838a1925bb3eb3b2440a8afd420e40/attach
Parameter List
Name Type Location Description Allowed Values Starting Version
usbDeviceUuid String url USB device UUID 2.2
vmInstanceUuid String body(contained in params structure) Virtual Machine UUID 2.2
attachType (Optional) String body(contained in params structure) Attach type
  • PassThrough
  • Redirect
 3.5.0
systemTags (Optional) List body System tags 2.2
userTags (Optional) List body User tags 2.2

API Response

Response Example

{
  "inventory": {
    "uuid": "dc782167a4853525848fd04bf606d072",
    "name": "usb",
    "hostUuid": "dea6020aae7b3244be45eee6ae1d4d0f",
    "vmInstanceUuid": "33471e0ae8a33b3b8b0f295eff6e4db4",
    "state": "Enabled",
    "busNum": "001",
    "devNum": "001",
    "idVendor": "0781",
    "idProduct": "5591",
    "iManufacturer": "SanDisk",
    "iProduct": "Ultra USB 3.0",
    "iSerial": "000000000001",
    "usbVersion": "3.0",
    "attachType": "PassThrough"
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.2
inventory UsbDeviceInventory See inventory 2.2
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.2
description String Brief description of the error 2.2
details String Detailed error information 2.2
elaboration String Reserved field, defaults to null 2.2
opaque LinkedHashMap Reserved field, defaults to null 2.2
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.2
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.2
name String Resource name 2.2
description String Resource description 2.2
hostUuid String Host UUID 2.2
vmInstanceUuid String Virtual Machine UUID 2.2
busNum String Bus number 2.2
devNum String Device number 2.2
idVendor String VendorID 2.2
idProduct String ProductID 2.2
iManufacturer String Manufacturer 2.2
iProduct String Device type 2.2
iSerial String Serial number 2.2
usbVersion String USB version 2.2
attachType String Attach method 3.5.0
createDate Timestamp Create date 2.2
lastOpDate Timestamp Last update date 2.2
state UsbDeviceState See state 2.2
#state
Name Type Description Starting Version
name String Resource name 2.2
ordinal int The ordinal number. 2.2

SDK Examples

Java SDK
AttachUsbDeviceToVmAction action = new AttachUsbDeviceToVmAction();
action.usbDeviceUuid = "84838a1925bb3eb3b2440a8afd420e40";
action.vmInstanceUuid = "2a3697245a4a3e829a246e222c243688";
action.attachType = "PassThrough";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AttachUsbDeviceToVmAction.Result res = action.call();
Python SDK
AttachUsbDeviceToVmAction action = AttachUsbDeviceToVmAction()
action.usbDeviceUuid = "84838a1925bb3eb3b2440a8afd420e40"
action.vmInstanceUuid = "2a3697245a4a3e829a246e222c243688"
action.attachType = "PassThrough"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AttachUsbDeviceToVmAction.Result res = action.call()

DetachUsbDeviceFromVm

API Request

URLs
POST zstack/v1/usb-device/usb-devices/{usbDeviceUuid}/detach
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {},
  "systemTags": [],
  "userTags": []
}
Note: The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{}}' \
http://localhost:8080/zstack/v1/usb-device/usb-devices/17a5e98e5f943e8fafa01602d50cf3ad/detach
Parameter List
Name Type Location Description Allowed Values Starting Version
usbDeviceUuid String url USB device UUID 2.2
systemTags (Optional) List body System tags 2.2
userTags (Optional) List body User tags 2.2

API Response

On success, this API returns an empty JSON structure {}. On error, the returned JSON structure contains an error field, for example:
{
"error": {
"code": "SYS.1001",
"description": "A message or a operation timeout",
"details": "Create VM on KVM timeout after 300s"
    }
}

SDK Examples

Java SDK
DetachUsbDeviceFromVmAction action = new DetachUsbDeviceFromVmAction();
action.usbDeviceUuid = "5256c889e9f0489e8fd12b66d176fb7d";
action.sessionId = "8082962f2d304a3fbee969e6b4749338";
DetachUsbDeviceFromVmAction.Result res = action.call();
Python SDK
DetachUsbDeviceFromVmAction action = DetachUsbDeviceFromVmAction()
action.usbDeviceUuid = "ced1bbb139c54d1d973ddc38ae565244"
action.sessionId = "f6550a168b9847fca4c98df088d86c09"
DetachUsbDeviceFromVmAction.Result res = action.call()

GetUsbDeviceCandidatesForAttachingVm

API Request

URLs
GET zstack/v1/vm-instances/{vmInstanceUuid}/candidate-usb-devices
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/ab759c79169739cb9e13ff091c4fa386/candidate-usb-devices?attachType=PassThrough
Parameter List
Name Type Location Description Allowed Values Starting Version
vmInstanceUuid String url Virtual Machine UUID 2.2
attachType (Optional) String query Attach type
  • PassThrough
  • Redirect
 3.6.0
systemTags (Optional) List query System tags 2.2
userTags (Optional) List query User tags 2.2

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "b58b4b48b3b8398f93b8b529f6f5b53a",
      "name": "usb",
      "hostUuid": "9f7438cf6fd233cf8fc27d4f311326ca",
      "vmInstanceUuid": "ccdfb1d443433e1a8beac3a1d54374d5",
      "state": "Enabled",
      "busNum": "001",
      "devNum": "001",
      "idVendor": "0781",
      "idProduct": "5591",
      "iManufacturer": "SanDisk",
      "iProduct": "Ultra USB 3.0",
      "iSerial": "000000000001",
      "usbVersion": "3.0",
      "attachType": "PassThrough"
    }
  ]
}
Name Type Description Starting Version
success boolean Success 2.2
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.2
inventories List See inventories 2.2
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.2
description String Brief description of the error 2.2
details String Detailed error information 2.2
elaboration String Reserved field, defaults to null 2.2
opaque LinkedHashMap Reserved field, defaults to null 2.2
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.2
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.2
name String Resource name 2.2
description String Resource description 2.2
hostUuid String Host UUID 2.2
vmInstanceUuid String Virtual Machine UUID 2.2
busNum String Bus number 2.2
devNum String Device number 2.2
idVendor String VendorID 2.2
idProduct String ProductID 2.2
iManufacturer String Manufacturer 2.2
iProduct String Device type 2.2
iSerial String Serial number 2.2
usbVersion String USB version 2.2
attachType String Attach method 3.5.0
createDate Timestamp Create date 2.2
lastOpDate Timestamp Last update date 2.2
state UsbDeviceState See state 2.2
#state
Name Type Description Starting Version
name String Resource name 2.2
ordinal int The ordinal number. 2.2

SDK Examples

Java SDK
GetUsbDeviceCandidatesForAttachingVmAction action = new GetUsbDeviceCandidatesForAttachingVmAction();
action.vmInstanceUuid = "ab759c79169739cb9e13ff091c4fa386";
action.attachType = "PassThrough";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetUsbDeviceCandidatesForAttachingVmAction.Result res = action.call();
Python SDK
GetUsbDeviceCandidatesForAttachingVmAction action = GetUsbDeviceCandidatesForAttachingVmAction()
action.vmInstanceUuid = "ab759c79169739cb9e13ff091c4fa386"
action.attachType = "PassThrough"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetUsbDeviceCandidatesForAttachingVmAction.Result res = action.call()

QueryUsbDevice

API Request

URLs
GET zstack/v1/usb-device/usb-devices
GET zstack/v1/usb-device/usb-devices/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 54e99d3cba30426599008210fe537a5a" \
-X GET http://localhost:8080/zstack/v1/usb-device/usb-devices
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth bd2e6629c65f4be6b0ae893664d80fac" \
-X GET http://localhost:8080/zstack/v1/usb-device/usb-devices/d2da293d46ac46279168ae02b361c69f

Queryable Fields

Run the CLI command tool, enter QueryUsbDevice and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "0beadc00381c4ca09216dc2ebfb0fba3",
      "name": "usb",
      "hostUuid": "648749ea79fb412aab27712c5813600a",
      "vmInstanceUuid": "f862f3c01f3340d6ab68e7a79757342f",
      "state": "Enabled",
      "busNum": "001",
      "devNum": "001",
      "idVendor": "0781",
      "idProduct": "5591",
      "iManufacturer": "SanDisk",
      "iProduct": "Ultra USB 3.0",
      "iSerial": "000000000001",
      "usbVersion": "3.0",
      "attachType": "PassThrough"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.2
inventories List See inventories 2.2
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.2
description String Brief description of the error 2.2
details String Detailed error information 2.2
elaboration String Reserved field, defaults to null 2.2
opaque LinkedHashMap Reserved field, defaults to null 2.2
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.2
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.2
name String Resource name 2.2
description String Resource description 2.2
hostUuid String Host UUID 2.2
vmInstanceUuid String Virtual Machine UUID 2.2
busNum String Bus number 2.2
devNum String Device number 2.2
idVendor String VendorID 2.2
idProduct String ProductID 2.2
iManufacturer String Manufacturer 2.2
iProduct String Device type 2.2
iSerial String Serial number 2.2
usbVersion String USB version 2.2
attachType String Attach method 3.6.0
createDate Timestamp Create date 2.2
lastOpDate Timestamp Last update date 2.2
state UsbDeviceState See state 2.2
#state
Name Type Description Starting Version
name String Resource name 2.2
ordinal int The ordinal number. 2.2

SDK Examples

Java SDK
QueryUsbDeviceAction action = new QueryUsbDeviceAction();
action.conditions = asList();
action.sessionId = "b51bb939a8844869abb32e9cedbc9a1f";
QueryUsbDeviceAction.Result res = action.call();
Python SDK
QueryUsbDeviceAction action = QueryUsbDeviceAction()
action.conditions = []
action.sessionId = "9f884d4333ba46369cd1039c9ea44965"
QueryUsbDeviceAction.Result res = action.call()

UpdateUsbDevice

API Request

URLs
PUT zstack/v1/usb-device/usb-devices/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateUsbDevice": {
    "name": "usb",
    "description": "this is a usb device",
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note: The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateUsbDevice":{"name":"usb","description":"this is a usb device","state":"Enabled"}}' \
http://localhost:8080/zstack/v1/usb-device/usb-devices/9d1ab4950ce933edabbaf8e73ca7e879/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.2
name (Optional) String body(contained in updateUsbDevice structure) Resource name 2.2
description (Optional) String body(contained in updateUsbDevice structure) Resource description 2.2
state (Optional) String body(contained in updateUsbDevice structure) USB device state
  • Enabled
  • Disabled
 2.2
systemTags (Optional) List body System tags 2.2
userTags (Optional) List body User tags 2.2

API Response

Response Example
{
  "inventory": {
    "uuid": "2695f7ce0bda4587bbabbbfaad080554",
    "description": "test usb",
    "hostUuid": "4261ceb358ce473fa62c137c1ba8d3ef",
    "vmInstanceUuid": "4c059c5e0a834d86984d3141d8ec42cb",
    "state": "Disabled",
    "idVendor": "10de",
    "idProduct": "0e0f",
    "iManufacturer": "SanDisk",
    "iProduct": "USB Storage",
    "iSerial": "000000000001",
    "usbVersion": "3.0",
    "attachType": "PassThrough"
  }
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.2
inventory UsbDeviceInventory See inventory 2.2
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.2
description String Brief description of the error 2.2
details String Detailed error information 2.2
elaboration String Reserved field, defaults to null 2.2
opaque LinkedHashMap Reserved field, defaults to null 2.2
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.2
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.2
name String Resource name 2.2
description String Resource description 2.2
hostUuid String Host UUID 2.2
vmInstanceUuid String Virtual Machine UUID 2.2
busNum String Bus number 2.2
devNum String Device number 2.2
idVendor String VendorID 2.2
idProduct String ProductID 2.2
iManufacturer String Manufacturer 2.2
iProduct String Device type 2.2
iSerial String Serial number 2.2
usbVersion String USB version 2.2
attachType String Attach method 3.6.0
createDate Timestamp Create date 2.2
lastOpDate Timestamp Last update date 2.2
state UsbDeviceState See state 2.2
#state
Name Type Description Starting Version
name String Resource name 2.2
ordinal int The ordinal number. 2.2

SDK Examples

Java SDK
UpdateUsbDeviceAction action = new UpdateUsbDeviceAction();
action.uuid = "86d05b807cfa47a7969745f0ffe8ee4b";
action.name = "usb";
action.description = "this is a usb device";
action.state = "Enabled";
action.sessionId = "86600ceaed5642ad810828129fe0e4a0";
UpdateUsbDeviceAction.Result res = action.call();
Python SDK
UpdateUsbDeviceAction action = UpdateUsbDeviceAction()
action.uuid = "f16940abc205404bb17b00367f5b6a8d"
action.name = "usb"
action.description = "this is a usb device"
action.state = "Enabled"
action.sessionId = "a65b10bd9a164d33a42d8bacfab5acd6"
UpdateUsbDeviceAction.Result res = action.call()
PreviousUSB Redirect Related InterfacesNextSR-IOV Related Interfaces
API Reference | ZStack ZSphere · ZVF | ZStack Resource Center