Querying Details About All Disks¶
Function¶
This API is used to query details about all disks.
Debugging¶
You can debug the API in which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.
URI¶
URI format
GET /v2/{project_id}/cloudvolumes/detail
Parameter description
Parameter
Mandatory
Description
project_id
Yes
The project ID.
For details about how to obtain the project ID, see Obtaining a Project ID.
Request query parameters
Parameter
Mandatory
Type
Description
availability_zone
No
String
The AZ information.
enterprise_project_id
No
String
The enterprise project ID for filtering. If parameter all_granted_eps is transferred, disks in all enterprise projects that are within the permission scope will be queried.
id
No
String
The disk ID.
ids
No
String
The disk IDs. The parameter value is in the ids=['id1','id2',...,'idx'] format. In the response, the ids value contains valid disk IDs only. Invalid disk IDs will be ignored. The details about a maximum of 60 disks can be queried. If parameters id and ids are both specified in the request, id will be ignored.
limit
No
Integer
The maximum number of query results that can be returned. The default value is 1000.
Minimum value: 1
Maximum value: 1000
Default value: 1000
marker
No
String
The pagination query by disk ID. The query starts from the first page by default. By specifying a disk ID for marker, information of all disks following the specified disk will be queried. Note that information of the specified disk will not be included in the query results.
metadata
No
String
The disk metadata.
multiattach
No
Boolean
Whether the disk is shareable. The value can be true (a shared disk) or false (a non-shared disk).
name
No
String
The disk name.
offset
No
Integer
The query offset. All disks after this offset will be queried. The value must be an integer greater than 0 but less than the number of disks.
server_id
No
String
The server ID.
service_type
No
String
The service type. Only EVS, DSS, and DESS are supported.
sort_dir
No
String
The result sorting order. The value can be asc (the ascending order) or desc (the descending order). The default value is desc.
sort_key
No
String
The keyword based on which the returned results are sorted. The value can be id, status, size, or created_at, and the default value is created_at.
status
No
String
The disk status. For details, see EVS Disk Status.
volume_type_id
No
String
The disk type ID. For details, see Querying EVS Disk Types. The disk type ID is the id value in the table that describes parameters in the volume_types field.
Request¶
The following example shows how to query the disks in the available state.
Example request
GET https://{endpoint}/v2/{project_id}/cloudvolumes/detail?status=available
Response¶
Response parameters
Parameter
Type
Description
volumes
Array of objects
The list of returned disks. For details, see Parameters in the volumes field.
count
Integer
The number of queried disks. This value is not affected by the pagination.
volumes_links
Array of Link objects
The query position marker in the disk list. If only some disks are returned in this query, the URL of the last disk queried will be returned. You can use this URL to continue to query the remaining disks in the next query.
error
Object
The error message returned if an error occurs. For details, see Parameters in the error field.
Parameters in the volumes field
Parameter
Type
Description
id
String
The disk ID.
links
Array of objects
The disk URI. For details, see Parameters in the links field.
name
String
The disk name.
status
String
The disk status. For details, see EVS Disk Status.
attachments
Array of objects
The disk attachment information. For details, see Parameters in the attachments field.
availability_zone
String
The AZ to which the disk belongs.
os-vol-host-attr:host
String
The reserved field.
source_volid
String
The source disk ID. This parameter has a value if the disk is created from a source disk.
This field is not supported currently.
snapshot_id
String
The snapshot ID. This parameter has a value if the disk is created from a snapshot.
description
String
The disk description.
os-vol-tenant-attr:tenant_id
String
The ID of the tenant to which the disk belongs. The tenant ID is the same as the project ID.
volume_image_metadata
Object
The metadata of the disk image.
Note
For details about volume_image_metadata, see Querying Image Details (Native OpenStack API) in the Image Management Service API Reference.
created_at
String
The time when the disk was created.
Time format: UTC YYYY-MM-DDTHH:MM:SS.XXXXXX
volume_type
String
The disk type.
The value can be SSD or SAS.
SSD: the ultra-high I/O type
SAS: the high I/O type
size
Integer
The disk size, in GB.
consistencygroup_id
String
The reserved field.
bootable
String
Whether the disk is bootable.
true: indicates a bootable disk.
false: indicates a non-bootable disk.
metadata
Map<String,Object>
The disk metadata. The encryption CMK ID in metadata. This parameter is used together with __system__encrypted for encryption. The length of cmkid is fixed at 36 bytes.
__system__encrypted: the encryption field in metadata. The value can be 0 (not encrypted) or 1 (encrypted). If this parameter does not appear, the encryption attribute of the disk is the same as that of the data source. If the disk is not created from a data source, the disk is not encrypted by default.
full_clone: The method of creation when the disk is created from a snapshot.
0: linked clone
1: full clone
hw:passthrough:
If this parameter is true, the disk device type is SCSI, which allows ECS OSs to directly access underlying storage media. SCSI reservation commands are supported.
If this parameter is false, the disk device type is VBD, which supports only simple SCSI read/write commands.
If this parameter does not appear, the disk device type is VBD.
updated_at
String
The time when the disk was updated. Time format: UTC YYYY-MM-DDTHH:MM:SS.XXXXXX
encrypted
Boolean
This field is not supported currently.
replication_status
String
The reserved field.
os-vol-mig-status-attr:migstat
String
The reserved field.
os-vol-host-attr:host
String
The reserved field.
os-vol-mig-status-attr:name_id
String
The reserved field.
os-volume-replication:extended_status
String
The reserved field.
shareable
String
Whether the disk is shareable. The value can be true (shared disk) or false (common disk). This field is no longer used. Use multiattach.
user_id
String
The reserved field.
service_type
String
The service type. The value can be EVS, DSS, or DESS.
dedicated_storage_id
String
The ID of the DSS storage pool accommodating the disk.
dedicated_storage_name
String
The name of the DSS storage pool accommodating the disk.
tags
Map<String,String>
The disk tags. This field has values if the disk has tags. Or, it is left empty.
wwn
String
The unique identifier used when attaching the disk.
multiattach
Boolean
Whether the disk is shareable.
true: indicates a shared disk.
false: indicates a non-shared disk.
enterprise_project_id
String
The ID of the enterprise project that the disk has been added to.
serial_number
String
The disk SN. This field is returned only for non-HyperMetro SCSI volumes and is used for disk mapping in the VM.
Parameters in the links field
Parameter
Type
Description
href
String
The corresponding shortcut link.
rel
String
The shortcut link marker name.
Parameters in the attachments field
Parameter
Type
Description
server_id
String
The ID of the server to which the disk is attached.
attachment_id
String
The ID of the attachment information.
attached_at
String
The time when the disk was attached.
Time format: UTC YYYY-MM-DDTHH:MM:SS.XXXXXX
host_name
String
The name of the physical host housing the cloud server to which the disk is attached.
volume_id
String
The disk ID.
device
String
The device name.
id
String
The ID of the attached disk.
Parameters in the error field
Parameter
Type
Description
message
String
The error message returned if an error occurs.
code
String
The error code returned if an error occurs.
For details about the error code, see Error Codes.
Example response
{ "count" : 1, "volumes" : [ { "attachments" : [ ], "availability_zone" : "az-dc-1", "bootable" : "false", "created_at" : "2016-05-25T02:42:10.856332", "description" : null, "id" : "b104b8db-170d-441b-897a-3c8ba9c5a214", "links" : [ { "href" : "https://volume.localdomain.com:8776/v2/dd14c6ac581f40059e27f5320b60bf2f/volumes/b104b8db-170d-441b-897a-3c8ba9c5a214", "rel" : "self" }, { "href" : "https://volume.localdomain.com:8776/dd14c6ac581f40059e27f5320b60bf2f/volumes/b104b8db-170d-441b-897a-3c8ba9c5a214", "rel" : "bookmark" } ], "metadata" : { }, "name" : "zjb_u25_test", "os-vol-host-attr:host" : "pod01.xxx#SATA", "volume_image_metadata" : { }, "os-vol-mig-status-attr:migstat" : null, "os-vol-mig-status-attr:name_id" : null, "os-vol-tenant-attr:tenant_id" : "dd14c6ac581f40059e27f5320b60bf2f", "os-volume-replication:extended_status" : null, "replication_status" : "disabled", "multiattach" : false, "size" : 1, "snapshot_id" : null, "status" : "available", "updated_at" : "2016-05-25T02:42:22.341984", "user_id" : "b0524e8342084ef5b74f158f78fc3049", "volume_type" : "SATA", "service_type" : "EVS", "dedicated_storage_id" : null, "dedicated_storage_name" : null, "wwn" : " 688860300000d136fa16f48f05992360" } ], "volumes_links" : [ { "href" : "https://volume.localdomain.com:8776/v2/dd14c6ac581f40059e27f5320b60bf2f/volumes/detail?limit=1&marker=b104b8db-170d-441b-897a-3c8ba9c5a214", "rel" : "next" } ] }
or
{ "error": { "message": "XXXX", "code": "XXX" } }
Status Codes¶
Normal
200
Error Codes¶
For details, see Error Codes.