Storage management
2.2.1 Query the shared file system list under a data center
API endpoint
GET /NSphere/api/storage/dc/{hpId}/shared-filesystem/list
API description
Query shared file systems by data center ID.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hpId | Data center ID | path | true | integer(int64) | |
title | Fuzzy match by shared file system display name. | query | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseListApiShareFileSystemVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | array | ApiShareFileSystemVO |
id | Shared file system ID | integer(int64) | |
name | Shared file system name | string | |
title | Shared file system display name | string | |
desc | Description. Length 0-120; any characters, including spaces, are allowed. | string | |
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system. | integer(int32) | |
typeStr | Shared file system type. iSCSI: iSCSI shared file system; FC: FC shared file system; NVMe-oF: NVMe-oF shared file system; netfs: NFS shared file system; iSER: iSER shared file system. | string | |
hpId | Data center ID | integer(int64) | |
path | Shared file system target path | string | |
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | integer(int32) | |
secretLevel | Security level. 1: internal; 2: secret; 3: confidential; 4: top secret. Only VMs of the same security level can use this storage pool. | integer(int32) | |
storageResourceId | Storage resource ID | integer(int64) | |
lockMode | Disk lock type. dlm: distributed lock; dlock: hardware-assisted lock (Ultra storage and NFS shared file system have no lock type). | string | |
maxSize | Total capacity (MB) | integer(int64) | |
allocation | Allocated capacity (MB) | number(double) | |
remainSize | Actual available capacity (MB) | integer(int64) | |
rsFsLunInfo | LUN information entity | array | ApiFsLunInfo |
id | LUN ID associated with the shared file system | integer(int64) | |
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | string | |
targetHost2 | Server IP address 2 | string | |
naa | NAA. Used for iSCSI or FC types. | string | |
naaName | NAA name | string | |
model | Model. Used for FC type. | string | |
lun | LUN. Used for iSCSI type. | string | |
lunView | LUN name | string | |
capacity | LUN capacity size (bytes). | integer(int64) | |
shareFileSystemId | Shared file system ID | integer(int64) | |
hba | HBA storage adapter. Used for FC type. | string | |
uuid | uuid. Used for NVMe-oF type. | string | |
subnqn | subnqn. Used for NVMe-oF type. | string | |
localAffinityHost | Host of the block device affinity IP | string | |
blockName | Corresponding block device name | string | |
localAffinityIp | Block device affinity IP | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"name": null,
"title": null,
"desc": null,
"type": null,
"typeStr": null,
"hpId": null,
"path": null,
"capacityControl": null,
"secretLevel": null,
"storageResourceId": null,
"lockMode": null,
"maxSize": null,
"allocation": null,
"remainSize": null,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"naaName": null,
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"lunView": "iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"shareFileSystemId": null,
"hba": null,
"uuid": null,
"subnqn": null,
"localAffinityHost": null,
"blockName": null,
"localAffinityIp": null
}
]
}
]
}
2.2.2 Query the storage volume and base image information attached to a VM
API endpoint
GET /NSphere/api/storage/domain/{domainId}/volume
API description
Query the storage volume and base image information attached to a VM by VM ID and base file path.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
domainId | VM ID | path | true | integer(int64) | |
path | Only letters, digits, hyphens, underscores, forward slashes (/), and dots are allowed. Must start with a forward slash (/) and must not contain consecutive slashes. | query | true | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiStorageNodeVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiStorageNodeVO | ApiStorageNodeVO |
id | Node tree ID. This field is not used. | integer(int64) | |
text | Text information; the content is the file name. | string | |
href | Hyperlink. This field is not used. | string | |
icon | Icon. This field is not used. | string | |
selectable | Whether the node can be selected. Used for UI highlighting. | boolean | |
nodes | Tree node information entity | array | ApiTreeNode |
id | Node tree ID. This field is not used. | integer(int64) | |
text | Text information; the content is the file name. | string | |
href | Hyperlink. This field is not used. | string | |
icon | Icon. This field is not used. | string | |
selectable | Whether the node can be selected. Used for UI highlighting. | boolean | |
nodes | Node tree | ||
fileName | File name | string | |
poolPath | Storage pool path | string | |
domainId | VM ID | integer(int64) | |
level | Tree node level | integer(int32) | |
domainName | VM name | string | |
title | VM display name | string | |
device | Device name | string | |
capacity | Capacity size (KB) | integer(int64) |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"text": null,
"href": null,
"icon": null,
"selectable": true,
"nodes": [
{
"id": null,
"text": null,
"href": null,
"icon": null,
"selectable": true,
"nodes": {}
}
],
"fileName": null,
"poolPath": null,
"domainId": null,
"level": null,
"domainName": null,
"title": null,
"device": null,
"capacity": null
}
}
2.2.3 Add a storage pool
API endpoint
POST /NSphere/api/storage/pool
API description
Add a storage pool for a specified host. When the task is successfully created, the task ID is returned.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"hostId": 1,
"name": "test",
"title": "test",
"type": "iscsi",
"path": "/dev/disk/by-id",
"hostName": null,
"srcHost": null,
"hostIp": null,
"remoteDir": null,
"srcName": null,
"fsType": null,
"fsId": null,
"hpName": null,
"multipath": false,
"srcHostNew": null,
"fcType": null,
"localPortName": null,
"fsName": null,
"aepIsetId": null,
"storageResourceId": null,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"hba": null,
"uuid": null,
"subnqn": null
}
],
"targetInfo": [
{
"ip": "127.0.0.1",
"port": null,
"target": "iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73"
}
],
"srcPath": null,
"userName": null,
"srcHostIp": null,
"pwd": null,
"authKey": null
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiAddStoragePoolDTO | Add-storage-pool entity | body | true | ApiAddStoragePoolDTO | ApiAddStoragePoolDTO |
hostId | Host ID | true | integer(int64) | ||
name | Storage pool name. Maximum length 32 characters. Only letters, digits, hyphens, underscores, and dots are allowed. The first character cannot be a hyphen or a dot, and the name cannot consist entirely of digits. When type is fs, the selected shared file system name is used directly. | true | string | ||
title | Storage pool display name. Maximum length 64 characters. Only Chinese characters, letters, digits, hyphens, underscores, spaces, and dots are allowed, and the name cannot consist entirely of spaces. When type is fs, the display name of the selected shared file system is used directly. | true | string | ||
type | Storage pool type. logical: LVM logical volume; iscsi: iSCSI network storage; nvme-of: NVMe-oF network storage; fc: FC network storage; dir: local file directory; netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; aep: Intel memory storage; upool: Ultra storage. | true | string | ||
path | Target path. When type is iscsi, nvme-of, fc, or iser, path is fixed to "/dev/disk/by-id". When type is dir or netfs, it must be a second-level directory starting with /vms, for example /vms/images. When type is fs, it is the shared file system directory. | false | string | ||
hostName | Host name | false | string | ||
srcHost | Source host | false | string | ||
hostIp | Host IP. Required when type is netfs or cifs, used as the server name or IP address. | false | string | ||
remoteDir | Remote directory (source path). Required when type is netfs or cifs, as the source path. | false | string | ||
srcName | Source storage name. Required when type is logical. | false | string | ||
fsType | Shared file system type. iscsi, nvme-of, fc, iser. Required when type is fs. | false | string | ||
fsId | Shared file system ID | false | integer(int64) | ||
hpName | Data center name | false | string | ||
multipath | Whether multipath is enabled | false | boolean | ||
srcHostNew | New name of the source host | false | string | ||
fcType | Storage type. block: block storage; fs: shared storage; dir: local file directory. | false | string | ||
localPortName | Local port name | false | string | ||
fsName | Shared file system name. Required when type is fs. | false | string | ||
aepIsetId | AEP ID. Currently only Intel Optane Memory (AEP) is supported. Required when type is aep. | false | string | ||
storageResourceId | Storage resource ID | false | integer(int64) | ||
rsFsLunInfo | LUN information entity. Required when adding a shared file system or storage pool. When editing a shared file system, this parameter can be modified only if no host has mounted the shared file system. (Not required for an NFS shared file system.) | false | array | ApiAddFsLunInfoDTO | |
id | LUN ID associated with the shared file system | false | integer(int64) | ||
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | false | string | ||
targetHost2 | Server IP address 2 | false | string | ||
naa | NAA. Required for iSCSI or FC types. Make sure the configured NAA is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
model | Model. Used for FC type. | false | string | ||
lun | LUN. Used for iSCSI type. | false | string | ||
capacity | LUN capacity size (bytes). Required for iSCSI, FC, or NVMe-oF types. | false | integer(int64) | ||
hba | HBA storage adapter. Used for FC type. Required when adding FC shared storage on a host. | false | string | ||
uuid | uuid. Used for NVMe-oF type. | false | string | ||
subnqn | subnqn. Used for NVMe-oF type. Make sure the configured namespace is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
targetInfo | Target information entity. Required when a host adds an iscsi, nvme-of, fc, or iser network storage pool. | false | array | ApiTargetInfo | |
ip | target IP | false | string | ||
port | target port | false | integer(int32) | ||
target | target name | false | string | ||
srcPath | Source path. Required when type is logical. | false | string | ||
userName | User name. Required when type is cifs. | false | string | ||
srcHostIp | Source host IP | false | string | ||
pwd | Password. Either this or authKey must be provided. Transmitted in plain text. Required when type is cifs. | false | string | ||
authKey | Alternative to pwd; either this or pwd must be provided. Transmitted encrypted. Required when type is cifs. | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID; can be used to query task progress. | integer(int64) | |
targetId | Task execution target ID | integer(int64) | |
targetName | Task execution target name | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.2.4 Delete a storage pool
API endpoint
DELETE /NSphere/api/storage/pool
API description
Delete a storage pool by its name for a specified host. When the task is successfully created, the task ID is returned.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | query | true | integer(int64) | |
poolName | Storage pool name | query | true | string | |
force | Whether to force delete. If a shut-down VM is still using the storage pool, delete the active storage pool as well. | query | false | boolean |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID; can be used to query task progress. | integer(int64) | |
targetId | Task execution target ID | integer(int64) | |
targetName | Task execution target name | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.2.5 Refresh a storage pool
API endpoint
PUT /NSphere/api/storage/pool/{hostId}/refresh
API description
Refresh a storage pool by its name for a specified host.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | path | true | integer(int64) | |
poolName | Storage pool name | query | true | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.6 Start a storage pool
API endpoint
PUT /NSphere/api/storage/pool/{hostId}/start
API description
Start a storage pool by its name for a specified host.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | path | true | integer(int64) | |
poolName | Storage pool name | query | true | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.7 View storage pool details
API endpoint
GET /NSphere/api/storage/pool/info
API description
Query the details of a specified storage pool under a specified host.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | query | true | integer(int64) | |
poolName | Storage pool name | query | true | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiStoragePoolDetailVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiStoragePoolDetailVO | ApiStoragePoolDetailVO |
type | Storage type name (Chinese/English) | string | |
name | Storage pool name | string | |
title | Storage pool display name | string | |
path | Storage pool path | string | |
totalSize | Total capacity (MB) | integer(int64) | |
allocation | Allocated capacity (MB) | number(double) | |
freeSize | Actual available capacity (MB) | integer(int64) | |
status | Storage pool status. 1: active; 0: inactive. | integer(int32) | |
fcType | Storage pool type. logical: LVM logical volume; iscsi: iSCSI network storage; nvme-of: NVMe-oF network storage; fc: FC network storage; dir: local file directory; netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; aep: Intel memory storage; upool: Ultra storage. | string | |
rsFsLunInfo | LUN information entity | array | ApiFsLunInfo |
id | LUN ID associated with the shared file system | integer(int64) | |
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | string | |
targetHost2 | Server IP address 2 | string | |
naa | NAA. Used for iSCSI or FC types. | string | |
naaName | NAA name | string | |
model | Model. Used for FC type. | string | |
lun | LUN. Used for iSCSI type. | string | |
lunView | LUN name | string | |
capacity | LUN capacity size (bytes). | integer(int64) | |
shareFileSystemId | Shared file system ID | integer(int64) | |
hba | HBA storage adapter. Used for FC type. | string | |
uuid | uuid. Used for NVMe-oF type. | string | |
subnqn | subnqn. Used for NVMe-oF type. | string | |
localAffinityHost | Host of the block device affinity IP | string | |
blockName | Corresponding block device name | string | |
localAffinityIp | Block device affinity IP | string | |
fsType | Shared file system type. iscsi, nvme-of, fc, iser. | string | |
srcPath | Source path | string | |
userName | User name | string | |
srcHostIp | Source host IP | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"type": null,
"name": null,
"title": null,
"path": null,
"totalSize": null,
"allocation": null,
"freeSize": null,
"status": null,
"fcType": null,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"naaName": null,
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"lunView": "iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"shareFileSystemId": null,
"hba": null,
"uuid": null,
"subnqn": null,
"localAffinityHost": null,
"blockName": null,
"localAffinityIp": null
}
],
"fsType": null,
"srcPath": null,
"userName": null,
"srcHostIp": null
}
}
2.2.8 Query the storage pool list
API endpoint
GET /NSphere/api/storage/pool/list
API description
Query storage pool information under hosts by the specified data center, cluster, or host ID. When multiple parameters are provided, only one takes effect; priority order: host ID, cluster ID, data center ID. If no condition is specified, the full data set is returned.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | query | false | integer(int64) | |
clusterId | Cluster ID | query | false | integer(int64) | |
hpId | Data center ID | query | false | integer(int64) | |
title | Fuzzy match by storage pool display name (case sensitive). | query | false | string | |
status | Storage pool status. 1: active; 0: inactive. | query | false | integer(int32) |
Response status
Status code | Description | schema |
200 | OK | ApiResponseListApiStoragePoolVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | array | ApiStoragePoolVO |
hostName | Host name | string | |
type | Storage pool type. logical: LVM logical volume; iscsi: iSCSI network storage; nvme-of: NVMe-oF network storage; fc: FC network storage; dir: local file directory; netfs: NFS network file system; fs: shared file system; cifs: Windows shared directory; aep: Intel memory storage; upool: Ultra storage. | string | |
name | Storage pool name | string | |
title | Storage pool display name | string | |
path | Storage pool path | string | |
totalSize | Total capacity (MB) | integer(int64) | |
allocation | Allocated capacity (MB) | number(double) | |
freeSize | Actual available capacity (MB) | integer(int64) | |
autoStart | Whether auto-start is enabled | boolean | |
symbolic | Whether the storage medium has been configured | boolean | |
status | Storage pool status. 1: active; 0: inactive. | integer(int32) |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"hostName": null,
"type": null,
"name": null,
"title": null,
"path": null,
"totalSize": null,
"allocation": null,
"freeSize": null,
"autoStart": true,
"symbolic": true,
"status": null
}
]
}
2.2.9 Add a shared file system
API endpoint
POST /NSphere/api/storage/shared-filesystem
API description
Add a shared file system.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"name": "test",
"title": "test",
"desc": null,
"type": 1,
"hpId": 1,
"ip": "127.0.0.1",
"capacityControl": 1,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"hba": null,
"uuid": null,
"subnqn": null
}
],
"secretLevel": 1,
"storageResourceId": null,
"remoteDir": "/export/data"
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiAddShareFileSystemDTO | Add-shared-file-system entity | body | true | ApiAddShareFileSystemDTO | ApiAddShareFileSystemDTO |
name | Shared file system name. Maximum length 32 characters. Only letters, digits, hyphens, underscores, and dots are allowed. The first character cannot be a hyphen or a dot, and the name cannot consist entirely of digits. | true | string | ||
title | Shared file system display name. Maximum length 32 characters. Only Chinese characters, letters, digits, hyphens, underscores, spaces, and dots are allowed, and the name cannot consist entirely of spaces. | true | string | ||
desc | Description. Length 0-120; any characters, including spaces, are allowed. | false | string | ||
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system. | true | integer(int32) | ||
hpId | Data center ID | true | integer(int64) | ||
ip | IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. When adding a shared file system, either this or the storageResourceId parameter must be provided. | false | string | ||
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | true | integer(int32) | ||
rsFsLunInfo | LUN information entity. Required when adding a shared file system or storage pool. When editing a shared file system, this parameter can be modified only if no host has mounted the shared file system. (Not required for an NFS shared file system.) | false | array | ApiAddFsLunInfoDTO | |
id | LUN ID associated with the shared file system | false | integer(int64) | ||
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | false | string | ||
targetHost2 | Server IP address 2 | false | string | ||
naa | NAA. Required for iSCSI or FC types. Make sure the configured NAA is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
model | Model. Used for FC type. | false | string | ||
lun | LUN. Used for iSCSI type. | false | string | ||
capacity | LUN capacity size (bytes). Required for iSCSI, FC, or NVMe-oF types. | false | integer(int64) | ||
hba | HBA storage adapter. Used for FC type. Required when adding FC shared storage on a host. | false | string | ||
uuid | uuid. Used for NVMe-oF type. | false | string | ||
subnqn | subnqn. Used for NVMe-oF type. Make sure the configured namespace is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
secretLevel | Security level. 1: internal; 2: secret; 3: confidential; 4: top secret. Only VMs of the same security level can use this storage pool. | true | integer(int32) | ||
storageResourceId | Storage resource ID. When adding a shared file system, either this or the ip parameter must be provided. | false | integer(int64) | ||
remoteDir | Remote directory (source path). NFS remote directory. Required when the shared file system type is NFS (type=4). | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.10 Edit a shared file system
API endpoint
PUT /NSphere/api/storage/shared-filesystem
API description
Edit a shared file system. If a host has already mounted the shared file system, only the display name, description, and VM auto-deployment control flag can be modified.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"id": 1,
"name": "name",
"title": "title",
"desc": null,
"type": 1,
"hpId": 1,
"ip": null,
"capacityControl": 1,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"hba": null,
"uuid": null,
"subnqn": null
}
],
"secretLevel": 1,
"storageResourceId": null,
"readOnly": false,
"isMerge": null,
"isSpeed": null,
"ioControl": null,
"delayThreshold": null,
"remoteDir": "/export/data"
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiEditShareFileSystemDTO | Edit-shared-file-system entity | body | true | ApiEditShareFileSystemDTO | ApiEditShareFileSystemDTO |
id | Shared file system ID | true | integer(int64) | ||
name | Shared file system name; can be modified only when no host has mounted the shared file system. Maximum length 32 characters. Only letters, digits, hyphens, underscores, and dots are allowed. The first character cannot be a hyphen or a dot, and the name cannot consist entirely of digits. | true | string | ||
title | Shared file system display name. Maximum length 32 characters. Only Chinese characters, letters, digits, hyphens, underscores, spaces, and dots are allowed, and the name cannot consist entirely of spaces. | true | string | ||
desc | Description. Length 0-120; any characters, including spaces, are allowed. | false | string | ||
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system. This parameter cannot be modified. | true | integer(int32) | ||
hpId | Data center ID. This parameter cannot be modified. | true | integer(int64) | ||
ip | IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. This parameter can be modified only when no host has mounted the shared file system. | false | string | ||
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | true | integer(int32) | ||
rsFsLunInfo | LUN information entity. Required when adding a shared file system or storage pool. When editing a shared file system, this parameter can be modified only if no host has mounted the shared file system. (Not required for an NFS shared file system.) | false | array | ApiAddFsLunInfoDTO | |
id | LUN ID associated with the shared file system | false | integer(int64) | ||
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | false | string | ||
targetHost2 | Server IP address 2 | false | string | ||
naa | NAA. Required for iSCSI or FC types. Make sure the configured NAA is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
model | Model. Used for FC type. | false | string | ||
lun | LUN. Used for iSCSI type. | false | string | ||
capacity | LUN capacity size (bytes). Required for iSCSI, FC, or NVMe-oF types. | false | integer(int64) | ||
hba | HBA storage adapter. Used for FC type. Required when adding FC shared storage on a host. | false | string | ||
uuid | uuid. Used for NVMe-oF type. | false | string | ||
subnqn | subnqn. Used for NVMe-oF type. Make sure the configured namespace is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
secretLevel | Security level. 1: internal; 2: secret; 3: confidential; 4: top secret. Only VMs of the same security level can use this storage pool. This parameter can be modified only when no host has mounted the shared file system. | true | integer(int32) | ||
storageResourceId | Storage resource ID. This parameter cannot be modified. | false | integer(int64) | ||
readOnly | Whether read-only | false | boolean | ||
isMerge | Whether LUN merging is supported. 0: not supported; 1: supported. | false | integer(int32) | ||
isSpeed | Whether storage acceleration is supported. 0: not supported; 1: supported. | false | integer(int32) | ||
ioControl | Storage I/O control. 0: disabled; 1: enabled. | false | integer(int32) | ||
delayThreshold | I/O latency threshold (ms) | false | integer(int32) | ||
remoteDir | Remote directory (source path). NFS remote directory. Required when the shared file system type is NFS (type=4). | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.11 Query shared file system details
API endpoint
GET /NSphere/api/storage/shared-filesystem/{id}
API description
Query the details of a shared file system by its ID.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
id | Shared file system ID | path | true | integer(int64) |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiShareFileSystemDetailVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiShareFileSystemDetailVO | ApiShareFileSystemDetailVO |
id | Shared file system ID | integer(int64) | |
name | Shared file system name | string | |
title | Shared file system display name | string | |
desc | Description. Length 0-120; any characters, including spaces, are allowed. | string | |
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system; 13: Ultra storage. | integer(int32) | |
hpId | Data center ID | integer(int64) | |
path | Shared file system target path | string | |
ip | IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | string | |
target | target name | string | |
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | integer(int32) | |
secretLevel | Security level. 1: internal; 2: secret; 3: confidential; 4: top secret. Only VMs of the same security level can use this storage pool. | integer(int32) | |
storageResourceId | Storage resource ID | integer(int64) | |
lockMode | Disk lock type. dlm: distributed lock; dlock: hardware-assisted lock (Ultra storage and NFS shared file system have no lock type). | string | |
rsFsLunInfo | LUN information entity | array | ApiFsLunInfo |
id | LUN ID associated with the shared file system | integer(int64) | |
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | string | |
targetHost2 | Server IP address 2 | string | |
naa | NAA. Used for iSCSI or FC types. | string | |
naaName | NAA name | string | |
model | Model. Used for FC type. | string | |
lun | LUN. Used for iSCSI type. | string | |
lunView | LUN name | string | |
capacity | LUN capacity size (bytes). | integer(int64) | |
shareFileSystemId | Shared file system ID | integer(int64) | |
hba | HBA storage adapter. Used for FC type. | string | |
uuid | uuid. Used for NVMe-oF type. | string | |
subnqn | subnqn. Used for NVMe-oF type. | string | |
localAffinityHost | Host of the block device affinity IP | string | |
blockName | Corresponding block device name | string | |
localAffinityIp | Block device affinity IP | string | |
readOnly | Whether read-only | boolean | |
isMerge | Whether LUN merging is supported. 0: not supported; 1: supported. | integer(int32) | |
isSpeed | Whether storage acceleration is supported. 0: not supported; 1: supported. | integer(int32) | |
ioControl | Storage I/O control. 0: disabled; 1: enabled. | integer(int32) | |
delayThreshold | I/O latency threshold (ms) | integer(int32) | |
clusterId | Cluster ID. Has a value only when the type is Ultra storage (type=13). | integer(int64) | |
dataPool | Data pool. Has a value only when the type is Ultra storage (type=13). | string | |
diskPool | Disk pool. Has a value only when the type is Ultra storage (type=13). | string | |
remoteDir | Remote directory (source path). NFS remote directory. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"id": null,
"name": null,
"title": null,
"desc": null,
"type": null,
"hpId": null,
"path": null,
"ip": null,
"target": null,
"capacityControl": null,
"secretLevel": null,
"storageResourceId": null,
"lockMode": null,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"naaName": null,
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"lunView": "iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"shareFileSystemId": null,
"hba": null,
"uuid": null,
"subnqn": null,
"localAffinityHost": null,
"blockName": null,
"localAffinityIp": null
}
],
"readOnly": true,
"isMerge": null,
"isSpeed": null,
"ioControl": null,
"delayThreshold": null,
"clusterId": null,
"dataPool": null,
"diskPool": null,
"remoteDir": null
}
}
2.2.12 Format a shared file system
API endpoint
POST /NSphere/api/storage/shared-filesystem/format
API description
Format a specified cluster or host shared file system. When the task is successfully created, the task ID is returned.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"id": 1,
"maxAccessNum": 64,
"fsName": "fsName",
"hostId": 1,
"clusterId": 1,
"poolName": "poolName",
"title": "fsTitle",
"lockType": "dlm",
"formSize": 1024
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiFormatOcfsDTO | Shared file system format information entity | body | true | ApiFormatOcfsDTO | ApiFormatOcfsDTO |
id | Shared file system ID | true | integer(int64) | ||
maxAccessNum | Maximum number of access nodes. Value range: integer 1-64. | true | integer(int32) | ||
fsName | Shared file system name | true | string | ||
hostId | Host ID. Required when formatting shared storage under a host. | false | integer(int64) | ||
clusterId | Cluster ID. Required when formatting a shared file system at the data center or cluster level. | false | integer(int64) | ||
poolName | Storage pool name | true | string | ||
title | Shared file system display name | true | string | ||
lockType | Disk lock type. dlm: distributed lock; dlock: hardware-assisted lock (Ultra storage and NFS shared file system have no lock type). If not provided, defaults to dlm. If dlock is selected, the storage server must support CAW. | true | string | ||
formSize | Format cluster size (KB). Valid values: 128, 256, 512, 1024. If not provided, defaults to 1024. | true | integer(int32) |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID; can be used to query task progress. | integer(int64) | |
targetId | Task execution target ID | integer(int64) | |
targetName | Task execution target name | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.2.13 Query the list of valid hosts using shared file systems under a cluster
API endpoint
GET /NSphere/api/storage/shared-filesystem/hosts
API description
Query the list of valid hosts using shared file systems under a cluster.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
clusterId | Cluster ID | query | true | integer(int64) | |
fsId | Shared file system ID. Either this or the fsName parameter must be provided. If fsId is not null, the query uses fsId; if fsId is null, the query uses fsName. | query | false | integer(int64) | |
fsName | Shared storage name. Either this or the fsId parameter must be provided. If fsId is not null, the query uses fsId; if fsId is null, the query uses fsName. | query | false | string | |
sortField | Sort field. Supported fields: name, ip, status, poolStatus, initiatorName. | query | false | string | |
sortDir | Sort direction. Not passed or 0: no sorting; 1: ascending; 2: descending. When sortField is empty, no sorting is applied by default. | query | false | integer(int32) |
Response status
Status code | Description | schema |
200 | OK | ApiResponseListApiShareFileHost |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | array | ApiShareFileHost |
id | Host ID. Required when adding a shared file system and creating shared storage. | integer(int64) | |
name | Host name. Required when adding a shared file system and creating shared storage. | string | |
ip | Host IP | string | |
status | Host status. 0: abnormal; 1: normal; 2: not in HA cluster; 3: maintenance; 4: maintenance (local storage failure); 5: isolated; 6: storage-network isolated. | integer(int32) | |
poolStatus | Storage pool status. 1: active; 0: inactive. | integer(int32) | |
initiatorName | Identifier | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": 1,
"name": "cvk1",
"ip": null,
"status": null,
"poolStatus": null,
"initiatorName": null
}
]
}
2.2.14 Query the shared file system list
API endpoint
GET /NSphere/api/storage/shared-filesystem/list
API description
Get shared file system and Ultra storage information for a specified cluster.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
clusterId | Cluster ID | query | true | integer(int64) | |
title | Fuzzy match by shared file system display name. | query | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseListApiClusterShareFileVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | array | ApiClusterShareFileVO |
id | Shared file system ID | integer(int64) | |
name | Shared file system name | string | |
title | Shared file system display name | string | |
desc | Description. Length 0-120; any characters, including spaces, are allowed. | string | |
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system. | integer(int32) | |
typeStr | Shared file system type. iSCSI: iSCSI shared file system; FC: FC shared file system; NVMe-oF: NVMe-oF shared file system; netfs: NFS shared file system; iSER: iSER shared file system. | string | |
hpId | Data center ID | integer(int64) | |
path | Shared file system target path | string | |
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | integer(int32) | |
maxSize | Total capacity (MB) | integer(int64) | |
allocation | Allocated capacity (MB) | number(double) | |
remainSize | Actual available capacity (MB) | integer(int64) | |
usAge | Utilization: (total capacity - available capacity) / total capacity; unit: %. | number(double) | |
alloRatio | Allocation ratio (allocated capacity / total capacity). | number(double) | |
rsFsLunInfo | LUN information entity | array | ApiFsLunInfo |
id | LUN ID associated with the shared file system | integer(int64) | |
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | string | |
targetHost2 | Server IP address 2 | string | |
naa | NAA. Used for iSCSI or FC types. | string | |
naaName | NAA name | string | |
model | Model. Used for FC type. | string | |
lun | LUN. Used for iSCSI type. | string | |
lunView | LUN name | string | |
capacity | LUN capacity size (bytes). | integer(int64) | |
shareFileSystemId | Shared file system ID | integer(int64) | |
hba | HBA storage adapter. Used for FC type. | string | |
uuid | uuid. Used for NVMe-oF type. | string | |
subnqn | subnqn. Used for NVMe-oF type. | string | |
localAffinityHost | Host of the block device affinity IP | string | |
blockName | Corresponding block device name | string | |
localAffinityIp | Block device affinity IP | string | |
remoteDir | Remote directory (source path). NFS remote directory. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"id": null,
"name": null,
"title": null,
"desc": null,
"type": null,
"typeStr": null,
"hpId": null,
"path": null,
"capacityControl": null,
"maxSize": null,
"allocation": null,
"remainSize": null,
"usAge": null,
"alloRatio": null,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"naaName": null,
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"lunView": "iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"shareFileSystemId": null,
"hba": null,
"uuid": null,
"subnqn": null,
"localAffinityHost": null,
"blockName": null,
"localAffinityIp": null
}
],
"remoteDir": null
}
]
}
2.2.15 Add a shared file system and create shared storage
API endpoint
POST /NSphere/api/storage/shared-storage
API description
Add a shared file system and create shared storage.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"name": "test",
"title": "test",
"desc": null,
"type": 1,
"hpId": 1,
"ip": "127.0.0.1",
"capacityControl": 1,
"rsFsLunInfo": [
{
"id": null,
"targetHost": "127.0.0.1",
"targetHost2": null,
"naa": "3664ae847f4dd4738874a7108a49341ad",
"model": null,
"lun": "ip-127.0.0.1:3260-iscsi-iqn.2018-01.com.ultrastor:8a38e898fc84484b9d24439cd1398d73-lun-4",
"capacity": 4560255975424,
"hba": null,
"uuid": null,
"subnqn": null
}
],
"secretLevel": 1,
"storageResourceId": null,
"remoteDir": "/export/data",
"hostShareFiles": [
{
"id": 1,
"name": "cvk1",
"ip": null,
"status": null,
"poolStatus": null,
"initiatorName": null
}
]
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiAddShareStoragePoolDTO | Add-shared-file-system entity | body | true | ApiAddShareStoragePoolDTO | ApiAddShareStoragePoolDTO |
name | Shared file system name. Maximum length 32 characters. Only letters, digits, hyphens, underscores, and dots are allowed. The first character cannot be a hyphen or a dot, and the name cannot consist entirely of digits. | true | string | ||
title | Shared file system display name. Maximum length 32 characters. Only Chinese characters, letters, digits, hyphens, underscores, spaces, and dots are allowed, and the name cannot consist entirely of spaces. | true | string | ||
desc | Description. Length 0-120; any characters, including spaces, are allowed. | false | string | ||
type | Shared file system type. 1: iSCSI shared file system; 2: FC shared file system; 3: NVMe-oF shared file system; 4: NFS shared file system; 5: iSER shared file system. | true | integer(int32) | ||
hpId | Data center ID | true | integer(int64) | ||
ip | IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. When adding a shared file system, either this or the storageResourceId parameter must be provided. | false | string | ||
capacityControl | Whether VM auto-deployment control is allowed. 0: not allowed; 1: allowed. | true | integer(int32) | ||
rsFsLunInfo | LUN information entity. Required when adding a shared file system or storage pool. When editing a shared file system, this parameter can be modified only if no host has mounted the shared file system. (Not required for an NFS shared file system.) | false | array | ApiAddFsLunInfoDTO | |
id | LUN ID associated with the shared file system | false | integer(int64) | ||
targetHost | Server IP address. A single IP address indicates a single path; multiple IP addresses indicate multipath. When entering multiple IP addresses, separate them with semicolons (;), for example: 192.168.0.27;192.168.10.27;2001🔤ef::90. Note: in a hot-standby environment, both the active and standby management platforms must be able to reach the shared storage. | false | string | ||
targetHost2 | Server IP address 2 | false | string | ||
naa | NAA. Required for iSCSI or FC types. Make sure the configured NAA is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
model | Model. Used for FC type. | false | string | ||
lun | LUN. Used for iSCSI type. | false | string | ||
capacity | LUN capacity size (bytes). Required for iSCSI, FC, or NVMe-oF types. | false | integer(int64) | ||
hba | HBA storage adapter. Used for FC type. Required when adding FC shared storage on a host. | false | string | ||
uuid | uuid. Used for NVMe-oF type. | false | string | ||
subnqn | subnqn. Used for NVMe-oF type. Make sure the configured namespace is not already in use by another shared file system, network storage, template storage, or another management platform. | false | string | ||
secretLevel | Security level. 1: internal; 2: secret; 3: confidential; 4: top secret. Only VMs of the same security level can use this storage pool. | true | integer(int32) | ||
storageResourceId | Storage resource ID. When adding a shared file system, either this or the ip parameter must be provided. | false | integer(int64) | ||
remoteDir | Remote directory (source path). NFS remote directory. Required when the shared file system type is NFS (type=4). | false | string | ||
hostShareFiles | Host information entity to be added to the shared storage. Required when adding a shared file system and mounting it as shared storage. | true | array | ApiShareFileHost | |
id | Host ID. Required when adding a shared file system and creating shared storage. | true | integer(int64) | ||
name | Host name. Required when adding a shared file system and creating shared storage. | true | string | ||
ip | Host IP | false | string | ||
status | Host status. 0: abnormal; 1: normal; 2: not in HA cluster; 3: maintenance; 4: maintenance (local storage failure); 5: isolated; 6: storage-network isolated. | false | integer(int32) | ||
poolStatus | Storage pool status. 1: active; 0: inactive. | false | integer(int32) | ||
initiatorName | Identifier | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.16 Add a storage volume
API endpoint
POST /NSphere/api/storage/volume
API description
Add a storage volume to a storage pool under a host. Adding storage volumes on network storage pools is not supported. If the storage volume pre-allocation mode is zero-fill, the storage volume is added as a task.
Request Content-Type
application/json
Response Content-Type
application/json
Request example
{
"hostPoolId": null,
"fsId": null,
"hostId": 1,
"spName": "defaultpool",
"spTitle": null,
"volName": "testVolume",
"capacity": 1024,
"format": "qcow2",
"baseFile": null,
"encryptPw": null,
"mode": 2,
"clusterSize": "262144",
"secDir": null,
"diskSecret": false,
"kmsClusterId": null,
"encryptionType": null,
"algorithm": null
}
Request parameters
Parameter name | Description | Location | Required | Type | schema |
apiAddVolumeDTO | Add-storage-volume entity | body | true | ApiAddVolumeDTO | ApiAddVolumeDTO |
hostPoolId | Data center ID | false | integer(int64) | ||
fsId | Shared file system ID | false | integer(int64) | ||
hostId | Host ID | true | integer(int64) | ||
spName | Storage pool name | true | string | ||
spTitle | Storage pool display name | false | string | ||
volName | Storage volume name. Maximum length 100 characters. Only letters, digits, hyphens, underscores, and dots are allowed. The first character cannot be a hyphen or a dot, and the name cannot consist entirely of digits. For an encrypted storage volume, the name may only contain letters, digits, hyphens, underscores, and dots, and the first character must be a letter. | true | string | ||
capacity | Maximum capacity (MB). The maximum capacity cannot exceed the available capacity of the storage pool. | true | integer(int64) | ||
format | Storage volume format. raw: high-speed; qcow2: intelligent. When diskSecret is true, only qcow2 can be passed. | true | string | ||
baseFile | Base image file. Effective only when the storage volume format is qcow2. | false | string | ||
encryptPw | Encryption password. Length 1-64 characters; cannot be entirely spaces. Does not take effect when encryptionType is 1. Required when diskSecret is true. | false | string | ||
mode | Pre-allocation. 0: lazy zero; 1: zero; 2: thin. | true | integer(int32) | ||
clusterSize | Cluster size (bytes). Valid values: 65536 (64K), 131072 (128K), 262144 (256K), 524288 (521K), 1048576 (1M), 2097152 (2M). Effective only when the storage volume format is qcow2. | false | string | ||
secDir | Second-level directory | false | string | ||
diskSecret | Whether the disk is encrypted. Required when diskSecret is true. | false | boolean | ||
kmsClusterId | KMS server cluster ID. Required when encryptionType is 1. | false | integer(int64) | ||
encryptionType | Encryption method. 0: local encryption; 1: KMS server encryption. Empty means no encryption. Required when diskSecret is true. | false | integer(int32) | ||
algorithm | Encryption algorithm. Valid values: aes, sm4. Required when diskSecret is true. | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiTaskMsgVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiTaskMsgVO | ApiTaskMsgVO |
msgId | Message ID; can be used to query task progress. | integer(int64) | |
targetId | Task execution target ID | integer(int64) | |
targetName | Task execution target name | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"msgId": 0,
"targetId": null,
"targetName": null
}
}
2.2.17 Delete a storage volume
API endpoint
DELETE /NSphere/api/storage/volume
API description
Delete a specified storage volume from a storage pool under a host.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
poolName | Storage pool name | query | true | string | |
hostId | Host ID | query | true | integer(int64) | |
volName | Storage volume name | query | true | string | |
isWipeVolume | Whether to force destruction of data | query | false | boolean | |
secDir | Second-level directory. If not empty, the deleted volume is a storage volume under this second-level directory. | query | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseVoid |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | string |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {}
}
2.2.18 Batch query storage volume information
API endpoint
GET /NSphere/api/storage/volume/all
API description
Query storage volume information under hosts by the specified data center, cluster, or host ID. When multiple parameters are provided, only one takes effect; priority order: host ID, cluster ID, data center ID. If no condition is specified, the full data set is returned. The more VMs there are, the longer the API takes; reduce call frequency and narrow the parameter scope where possible. New API in E0930.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hpId | Data center ID | query | false | string | |
clusterId | Cluster ID | query | false | string | |
hostId | Host ID | query | false | string |
Response status
Status code | Description | schema |
200 | OK | ApiResponseListApiStorageVolumeBasicVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | array | ApiStorageVolumeBasicVO |
name | Storage volume name | string | |
size | Storage size (MB). No value when the type is directory (dir). | number(double) | |
allocation | Storage used space (MB). No value when the type is directory (dir). | number(double) | |
format | Storage file format. raw: high-speed; qcow2: intelligent; dir: directory; iso: image file; unknown: unknown; luks: encrypted. | string | |
users | User of this storage volume (VM name) | string | |
backingStore | Base image file | string | |
level | Incremental file level. 0 indicates an incremental file; a value greater than 0 indicates a base file. Empty means not an incremental file. | integer(int32) | |
isTempImg | Whether it is a template image file | boolean | |
baseFile | Whether it is a base image file | boolean | |
hostName | Host name | string | |
storagePoolName | Storage pool name | string | |
securityMode | Whether it is safe mode. 0: no; 1: yes. | integer(int32) | |
mode | Pre-allocation. 0: lazy zero; 1: zero; 2: thin. | integer(int32) | |
encryptionType | Encryption method. 0: local encryption; 1: KMS server encryption. Empty means no encryption. | integer(int32) | |
encrypt | Whether the disk is encrypted | boolean |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": [
{
"name": null,
"size": null,
"allocation": null,
"format": null,
"users": null,
"backingStore": null,
"level": null,
"isTempImg": true,
"baseFile": true,
"hostName": null,
"storagePoolName": null,
"securityMode": null,
"mode": null,
"encryptionType": null,
"encrypt": true
}
]
}
2.2.19 Query the storage volume list
API endpoint
GET /NSphere/api/storage/volume/list
API description
Query the storage volume list by host ID and storage pool name.
Request Content-Type
application/x-www-form-urlencoded
Response Content-Type
application/json
Request parameters
Parameter name | Description | Location | Required | Type | schema |
hostId | Host ID | query | true | integer(int64) | |
spName | Storage pool name | query | true | string | |
offset | Offset. Specifies the record number from which to start returning results. Value must be >= 0; default is 0. | query | false | integer(int32) | |
limit | Maximum number of records returned per page. Value 1-200; default is 10. | query | false | integer(int32) | |
sortDir | Sort direction. Not passed or 0: no sorting; 1: ascending; 2: descending. When sortField is empty, no sorting is applied by default. | query | false | integer(int32) | |
sortField | Sort field. Supported fields: name, size, allocation, format, users. | query | false | string | |
storageVolumeName | Fuzzy match by storage volume name (case insensitive). | query | false | string | |
secDir | Second-level directory | query | false | string | |
userName | User of this storage volume (VM name) | query | false | string | |
isEncrypt | Whether the disk is encrypted | query | false | boolean |
Response status
Status code | Description | schema |
200 | OK | ApiResponseApiPagingListResultApiStorageVolumeVO |
Response parameters
Parameter name | Description | Type | schema |
state | Status code. 0: success, 1: failure, 2: partial success | integer(int32) | integer(int32) |
errorCode | Error code. A non-zero value indicates a business error. | integer(int32) | integer(int32) |
successMessage | Success message | string | |
failureMessage | Error message; valid when the operation fails or partially succeeds. | string | |
data | Response data. If the status code is 0, this contains the normal returned data; if non-zero and non-empty, it contains the data required to describe the error. | ApiPagingListResultApiStorageVolumeVO | ApiPagingListResultApiStorageVolumeVO |
data | Storage volume entity | array | ApiStorageVolumeVO |
name | Storage volume name | string | |
size | Storage size (MB). No value when the type is directory (dir). | number(double) | |
allocation | Storage used space (MB). No value when the type is directory (dir). | number(double) | |
format | Storage file format. raw: high-speed; qcow2: intelligent; dir: directory; iso: image file; unknown: unknown; luks: encrypted. | string | |
users | User of this storage volume (VM name) | string | |
backingStore | Base image file | string | |
level | Incremental file level. 0 indicates an incremental file; a value greater than 0 indicates a base file. Empty means not an incremental file. | integer(int32) | |
isTempImg | Whether it is a template image file | boolean | |
baseFile | Whether it is a base image file | boolean | |
hostName | Host name | string | |
storagePoolName | Storage pool name | string | |
securityMode | Whether it is safe mode. 0: no; 1: yes. | integer(int32) | |
mode | Pre-allocation. 0: lazy zero; 1: zero; 2: thin. | integer(int32) | |
encryptionType | Encryption method. 0: local encryption; 1: KMS server encryption. Empty means no encryption. | integer(int32) | |
encrypt | Whether the disk is encrypted | boolean | |
naa | NAA name | string | |
blockName | Corresponding block device name. Only has a value when the storage volume is a block device. | string | |
localAffinityIp | Block device affinity IP. Only has a value when the storage volume is a locally-affine block device. | string | |
localAffinityHost | Host of the block device affinity IP. Only has a value when the storage volume is a locally-affine block device. | string | |
offset | Offset. Specifies the record number from which to start returning results. | integer(int32) | |
size | Number of records returned in the current response. | integer(int32) | |
total | Total number of records | integer(int64) |
Response example
{
"state": 0,
"errorCode": 0,
"successMessage": null,
"failureMessage": null,
"data": {
"data": [
{
"name": null,
"size": null,
"allocation": null,
"format": null,
"users": null,
"backingStore": null,
"level": null,
"isTempImg": true,
"baseFile": true,
"hostName": null,
"storagePoolName": null,
"securityMode": null,
"mode": null,
"encryptionType": null,
"encrypt": true,
"naa": null,
"blockName": null,
"localAffinityIp": null,
"localAffinityHost": null
}
],
"offset": null,
"size": null,
"total": null
}
}