此操作用来批量查询卷。可以通过设置过滤条件和range范围进行查询。如果未设置过滤条件和range范围，则查询所有的卷。

请求语法

GET /rest/v2/block/lun?filter=filter&range=i-j HTTP/1.1
Date: date
Host: ip:port
Authorization: authorization

请求参数

参数	类型	描述	是否必须
filter	String	查询的过滤条件。过滤条件由查询属性和属性值组成，其中属性和属性值之间用单个冒号分隔（key:value）表示模糊匹配，用两个冒号分隔（key::value）表示精确匹配。可以选择多个查询，如果是或的关系，使用“or”将查询条件分隔开；如果是与的关系，使用“and”将查询条件分隔开。支持的过滤条件类型包括： lunName：卷名称。 status：卷的状态。 capacity：卷容量。 iqn：target的识别。 isClone：是否是克隆卷，取值：true、false。 pool：存储池（仅集群版支持）。 cachePool：缓存存储池（仅集群版支持）。 storageMode：卷的存储类型。 path：数据目录（仅单机版支持）。	否
range	String	查询卷的范围，格式为i-j，i和j为正整数，0 < j-i < 1000。按照卷名称进行排序，返回第i到第j的卷。如果输入的查询范围超过卷的总个数，返回的结果为空，如果未指定range，则返回所有符合条件的卷。	否

参数

类型

描述

是否必须

filter

String

查询的过滤条件。

过滤条件由查询属性和属性值组成，其中属性和属性值之间用单个冒号分隔（key:value）表示模糊匹配，用两个冒号分隔（key::value）表示精确匹配。可以选择多个查询，如果是或的关系，使用“or”将查询条件分隔开；如果是与的关系，使用“and”将查询条件分隔开。

支持的过滤条件类型包括：

lunName：卷名称。
status：卷的状态。
capacity：卷容量。
iqn：target的识别。
isClone：是否是克隆卷，取值：true、false。
pool：存储池（仅集群版支持）。
cachePool：缓存存储池（仅集群版支持）。
storageMode：卷的存储类型。
path：数据目录（仅单机版支持）。

否

range

String

查询卷的范围，格式为i-j，i和j为正整数，0 < j-i < 1000。按照卷名称进行排序，返回第i到第j的卷。如果输入的查询范围超过卷的总个数，返回的结果为空，如果未指定range，则返回所有符合条件的卷。

否

响应结果

名称	类型	描述
luns	Array of lun	卷信息集合，详见“表1 响应参数lun说明”。

表1 响应参数lun说明

名称	类型	描述
lunName	String	卷名称。
status	String	卷的状态： Normal：正常。 Deleting：卷正在删除中。 DeleteFailed：卷删除失败。 Recovering：卷正在还原中。 RecoverFailed：卷还原失败。 Rollbacking：卷正在回滚。 Flattening：与快照的关系链断开过程中，表示克隆卷正在复制源卷的数据，复制完成之后将变成独立卷，不再依赖快照和源卷。 Importing：正在导入备份数据。 Wiping：卷正在清空数据。 WipeFailed：清空数据失败。 Suspended：卷挂起。 Suspending：卷正在挂起。 SuspendFailed：卷挂起失败。
progress	Double	卷还原进度百分比。仅卷状态为Recovering时显示。
recoverFailedReason	String	卷还原失败的原因。仅卷状态为RecoverFailed时显示。
deleteFailedReason	String	卷云上数据删除失败的原因。仅卷状态为DeleteFailed时显示。
wipeFailedReason	String	卷清空失败的原因。仅卷状态为WipeFailed时显示。
waitUploadBytes	String	待上传数据量，单位是bytes。仅卷状态为Suspending时显示。
SuspendFailedReason	String	卷挂起失败的原因。仅卷状态为SuspendFailed时显示。
storageMode	String	卷的存储类型： Local：本地模式，数据全部保留在本地。 Cache：缓存模式，本地保留部分热数据，全部数据异步存储到对象存储中。 Storage：存储模式，本地保留全部数据，并异步存储到对象存储中。
capacity	Integer	卷容量，单位是GiB。
createTime	Long	卷创建时间。unix时间戳（UTC），精确到毫秒。
iSCSITargets	Array of iSCSITarget	iSCSI target属性集合，详见“表2响应参数iSCSITarget说明”。
cloud	Object of cloud	卷的上云信息，详见“表4 响应参数cloud说明”。
config	Object of config	卷的配置信息，详见“表5 响应参数config说明”。
dataHealth	Object of dataHealth	卷数据的健康状况信息，详见“表10 响应参数dataHealth说明”。
number	Long	卷编号。
isClone	Boolean	是否是克隆卷： true：是克隆卷。 false：不是克隆卷。
sourceSnapshotName	String	对应的快照名称（仅克隆卷支持）。
sourceLunName	String	克隆卷的源卷名称（仅克隆卷支持）。
snapshots	Object of snapshot	卷的快照信息，详见“表11 响应参数snapshot说明”。
WWID	String	卷的唯一标识符。

表2 响应参数iSCSITarget说明

名称	类型	描述
iqn	String	iSCSI target IQN。
status	String	卷对应的target的状态： Active：主target。 Standby：热备target。 Offline：离线target。 Unavailable：冷备target。
ips	Array of ip	iSCSI target的IP属性集合，详见“表3 响应参数ip说明”。
serverId	String	IQN所在的服务器ID。

表3 响应参数ip说明

名称	类型	描述
ip	String	iSCSI target的IP。
port	Integer	iSCSI target的端口号。

表4 响应参数cloud说明

名称	类型	描述
bucketName	String	OOS存储桶的名称（仅上云卷支持）。
endpoint	String	OOS Endpoint（仅上云卷支持）。
signVersion	String	上云签名认证的类型（仅上云卷支持）： v2：V2签名认证。 v4：V4签名认证。
region	String	Endpoint资源池所在区域（仅上云卷支持）。
provider	String	对象存储服务名称： OOS：天翼云对象存储经典版I型。 S3：兼容S3的其他对象存储。

表5 响应参数config说明

名称	类型	描述
localStorageClass	String	卷冗余模式（仅集群版支持）： single-copy：单副本。 2-copy：两副本。 3-copy：三副本。 EC N+M。
minReplica	Integer	卷的最小副本数（仅集群版支持）。
sectorSize	Integer	扇区大小： 512。 4096。
highAvailability	String	高可用模式类型（仅集群版支持）： ActiveStandby：主备，该卷关联对应target下的所有IQN。 Disabled：禁用，该卷关联对应target下的1个IQN。
writePolicy	String	卷的写策略： WriteBack：回写，指数据写入到内存后即返回客户端成功，之后再异步写入磁盘。 WriteThrough：透写，指数据同时写入内存和磁盘，并在都写成功后再返回客户端成功。 WriteAround：绕写，指数据直接写到磁盘，不写入内存。
cachePool	String	缓存存储池（仅集群版支持）。
pool	String	存储池（仅集群版支持），表示最终存储池，卷数据最终落在该存储池内。
redundancyOverlap	Integer	卷的折叠副本数（仅集群版支持）。
reclaimPolicy	String	卷回收策略： Delete：当卷关联的快照全部删除后，卷自动删除。 Retain：当卷关联的快照全部删除后，卷仍然保留。
serverAffinity	Object	卷主备分布优先级设置，详见“表6 响应参数serverAffinity说明”。
compress	Object	卷本地数据的压缩策略，详见“表7 响应参数compress说明”。
qosPolicy	Object	卷关联的QoS策略信息，详见“表8 响应参数qosPolicy说明”。
qosPolicyforLUN	Object	卷所在存储池中卷的默认QoS策略信息（仅集群版支持），详见“表9 响应参数qosPolicyforLUN”。说明如果卷的缓存存储池和存储池同时存在时，展示缓存存储池的“存储池内卷的默认QoS策略”；如果缓存存储池未设置“存储池内卷的默认QoS策略”，则不返回此项。如果卷只有存储池：展示存储池的“存储池内卷的默认QoS策略”；如果存储池未设置“存储池内卷的默认QoS策略”，则不返回此项。
ECfragmentSize	String	分片大小。如果冗余模式为EC N+M，则会返回此项。
path	String	数据目录（仅单机版支持）。

表6 响应参数serverAffinity说明

名称	类型	描述
autoFailback	String	针对卷主备状态，当高优先级的服务器恢复正常后，是否自动进行主备状态切换（仅集群版支持）： Enabled：自动进行主备切换。 Disabled：不自动进行主备切换。
priority	Array of string	卷主备分布优先级的服务器ID（仅集群版支持），系统根据指定的服务器ID顺序来选择卷的主备IQN。

名称

类型

描述

autoFailback

String

针对卷主备状态，当高优先级的服务器恢复正常后，是否自动进行主备状态切换（仅集群版支持）：

Enabled：自动进行主备切换。
Disabled：不自动进行主备切换。

priority

Array of string

卷主备分布优先级的服务器ID（仅集群版支持），系统根据指定的服务器ID顺序来选择卷的主备IQN。

表7 响应参数compress说明

名称	类型	描述
algorithm	String	卷的本地数据压缩策略： None：不对卷本地数据进行压缩。 Zstd：使用Zstandard压缩算法对卷本地数据进行压缩。
zstdLevel	Integer	使用Zstandard压缩算法对卷本地数据进行压缩时，数据的压缩级别。说明压缩级别是一个在压缩速度与压缩比之间进行权衡的参数：级别值越低，压缩速度越快，但压缩率越低；级别值越高，压缩比越好，但压缩速度越慢，消耗的CPU和内存资源也更多。

名称

类型

描述

algorithm

String

卷的本地数据压缩策略：

None：不对卷本地数据进行压缩。
Zstd：使用Zstandard压缩算法对卷本地数据进行压缩。

zstdLevel

Integer

使用Zstandard压缩算法对卷本地数据进行压缩时，数据的压缩级别。

说明

压缩级别是一个在压缩速度与压缩比之间进行权衡的参数：级别值越低，压缩速度越快，但压缩率越低；级别值越高，压缩比越好，但压缩速度越慢，消耗的CPU和内存资源也更多。

表8 响应参数cqosPolicy说明

名称	类型	描述
qosName	String	QoS策略名称。

表9 响应参数qosPolicyforLUN说明

名称	类型	描述
qosName	String	QoS策略名称。
poolName	String	存储池名称。

表10 响应参数dataHealth说明

名称	类型	描述
normal	Double	卷正常数据的百分比。
lowRedundancy	Double	卷降级数据的百分比。
error	Double	卷错误数据的百分比。
reconstructionProgress	Double	当卷存在降级状态的数据时，数据重建进度的百分比。
ETR	Long	当卷存在降级数据时，预计剩余的数据重建时间。单位为秒。如果返回值为负数，说明数据无法重建，需用户尽快修复。

表11 响应参数snapshot说明

名称	类型	描述
snapshotNumbers	Integer	卷快照的数量（仅本地卷支持）。
snapshotSize	Long	卷关联的快照大小的总和（仅本地卷支持），即快照记录的数据量。单位是bytes。注意卷或上游快照删除可能导致大小波动。

名称

类型

描述

snapshotNumbers

Integer

卷快照的数量（仅本地卷支持）。

snapshotSize

Long

卷关联的快照大小的总和（仅本地卷支持），即快照记录的数据量。单位是bytes。

注意

卷或上游快照删除可能导致大小波动。

请求示例1

单机版：查询卷名称包含luna或lunb的卷。

GET /rest/v2/block/lun?filter=lunName:luna or lunName:lunb HTTP/1.1
Date: Wed, 17 Jun 2026 02:14:41 GMT
Authorization: userName:signature
Host: 192.168.0.66:1443

响应示例1

HTTP/1.1 200 OK 
x-hblock-request-id: 7fc294c2c9a44462ab634bdfe87d4e4a
Connection: keep-alive
Content-Length: 2315
Date: Wed, 17 Jun 2026 02:14:41 GMT
Content-Type: application/json;charset=utf-8
Server: HBlock

{
    "data": {
        "luns": [
            {
                "lunName": "luna1",
                "status": "Normal",
                "capacity": 100,
                "storageMode": "Local",
                "createTime": 1779774272040,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:targeta.1",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.66",
                                "port": 3260
                            }
                        ],
                        "serverId": "hblock_1"
                    }
                ],
                "config": {
                    "sectorSize": 4096,
                    "writePolicy": "WriteBack",
                    "path": "/mnt/stor01",
                    "reclaimPolicy": "Retain",
                    "compress": {
                        "algorithm": "None"
                    }
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 0,
                "isClone": false,
                "snapshots": {
                    "snapshotNumbers": 2,
                    "snapshotSize": 0
                },
                "WWID": "33fffffffcdfaf62d"
            },
            {
                "lunName": "luna1-C1",
                "status": "Normal",
                "capacity": 200,
                "storageMode": "Local",
                "createTime": 1781576166817,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:targeta1.3",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.66",
                                "port": 3260
                            }
                        ],
                        "serverId": "hblock_1"
                    }
                ],
                "config": {
                    "sectorSize": 4096,
                    "writePolicy": "WriteBack",
                    "path": "/mnt/stor01",
                    "reclaimPolicy": "Retain",
                    "compress": {
                        "algorithm": "None"
                    }
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 0,
                "isClone": true,
                "sourceSnapshotName": "luna1-snapshot",
                "sourceLunName": "luna1",
                "snapshots": {
                    "snapshotNumbers": 1,
                    "snapshotSize": 0
                },
                "WWID": "33fffffff922a5a0f"
            },
            {
                "lunName": "luna7",
                "status": "Normal",
                "capacity": 70,
                "storageMode": "Local",
                "createTime": 1781506644418,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:targeta.1",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.66",
                                "port": 3260
                            }
                        ],
                        "serverId": "hblock_1"
                    }
                ],
                "config": {
                    "sectorSize": 4096,
                    "writePolicy": "WriteBack",
                    "path": "/mnt/stor01",
                    "reclaimPolicy": "Retain",
                    "compress": {
                        "algorithm": "None"
                    }
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 1,
                "isClone": false,
                "snapshots": {
                    "snapshotNumbers": 0,
                    "snapshotSize": 0
                },
                "WWID": "33000000010c1ef9f"
            },
            {
                "lunName": "lunb2",
                "status": "Normal",
                "capacity": 220,
                "storageMode": "Cache",
                "createTime": 1781579618100,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:targetb.2",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.66",
                                "port": 3260
                            }
                        ],
                        "serverId": "hblock_1"
                    }
                ],
                "cloud": {
                    "bucketName": "hblocktest3",
                    "endpoint": "https://oos-cn.ctyunapi.cn",
                    "signVersion": "v2",
                    "provider": "OOS"
                },
                "config": {
                    "sectorSize": 4096,
                    "writePolicy": "WriteBack",
                    "path": "/mnt/stor01",
                    "reclaimPolicy": "Retain",
                    "compress": {
                        "algorithm": "Zstd",
                        "zstdLevel": 4
                    }
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 1,
                "WWID": "3300000004338de99"
            }
        ]
    }
}

请求示例2

集群版：查询卷名称包含lun01或lun02的卷，并且只列出第3个到第5个查询结果。

GET /rest/v2/block/lun?filter=lunName:lun01 or lunName:lun02 &range=3-5 HTTP/1.1
Date: Wed, 17 Jun 2026 02:29:31 GMT
Authorization: HBlock userName:signature
Connection: keep-alive
Host: 192.168.0.65:1443

响应示例2

HTTP/1.1 200 OK 
x-hblock-request-id: 0cab78d8531c45f1a4ef18dea90ef8fd
Connection: keep-alive
Content-Length: 3115
Date: Wed, 17 Jun 2026 02:29:31 GMT
Content-Type: application/json;charset=utf-8
Server: HBlock

{
    "data": {
        "luns": [
            {
                "lunName": "lun01a-c2",
                "status": "Normal",
                "capacity": 110,
                "storageMode": "Local",
                "createTime": 1781593182986,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target01.1",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.67",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_3"
                    },
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target01.2",
                        "status": "Standby",
                        "ips": [
                            {
                                "ip": "192.168.0.65",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_1"
                    }
                ],
                "config": {
                    "localStorageClass": "EC 2+1",
                    "minReplica": 2,
                    "sectorSize": 4096,
                    "highAvailability": "ActiveStandby",
                    "writePolicy": "WriteThrough",
                    "pool": "default-pool",
                    "redundancyOverlap": 1,
                    "reclaimPolicy": "Retain",
                    "serverAffinity": {
                        "autoFailback": "Enabled"
                    },
                    "compress": {
                        "algorithm": "Zstd",
                        "zstdLevel": 5
                    },
                    "ECfragmentSize": 16
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 7,
                "isClone": true,
                "sourceSnapshotName": "snap1",
                "sourceLunName": "lun01a",
                "snapshots": {
                    "snapshotNumbers": 0,
                    "snapshotSize": 0
                },
                "WWID": "33000000029abe0b5"
            },
            {
                "lunName": "lun01c",
                "status": "Normal",
                "capacity": 10,
                "storageMode": "Local",
                "createTime": 1781575688087,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target1.9",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.68",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_4"
                    },
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target1.10",
                        "status": "Standby",
                        "ips": [
                            {
                                "ip": "192.168.0.64",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_2"
                    }
                ],
                "config": {
                    "localStorageClass": "3-copy",
                    "minReplica": 1,
                    "sectorSize": 4096,
                    "highAvailability": "ActiveStandby",
                    "writePolicy": "WriteBack",
                    "pool": "default-pool",
                    "redundancyOverlap": 1,
                    "reclaimPolicy": "Retain",
                    "serverAffinity": {
                        "autoFailback": "Enabled"
                    },
                    "compress": {
                        "algorithm": "Zstd",
                        "zstdLevel": 5
                    }
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 0,
                "isClone": false,
                "snapshots": {
                    "snapshotNumbers": 1,
                    "snapshotSize": 0
                },
                "WWID": "33000000047098116"
            },
            {
                "lunName": "lun02b",
                "status": "Normal",
                "capacity": 210,
                "storageMode": "Cache",
                "createTime": 1781576842029,
                "iSCSITargets": [
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target02.4",
                        "status": "Active",
                        "ips": [
                            {
                                "ip": "192.168.0.64",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_2"
                    },
                    {
                        "iqn": "iqn.2012-08.cn.ctyunapi.oos:target02.3",
                        "status": "Standby",
                        "ips": [
                            {
                                "ip": "192.168.0.68",
                                "port": 3260
                            }
                        ],
                        "targetPortalIP": {
                            "ips": [
                                {
                                    "ip": "10.1.0.3",
                                    "port": 105
                                }
                            ],
                            "status": "Disabled"
                        },
                        "serverId": "hblock_4"
                    }
                ],
                "cloud": {
                    "bucketName": "hblocktest3",
                    "endpoint": "https://oos-cn.ctyunapi.cn",
                    "signVersion": "v2",
                    "provider": "OOS"
                },
                "config": {
                    "localStorageClass": "EC 2+1",
                    "minReplica": 2,
                    "sectorSize": 4096,
                    "highAvailability": "ActiveStandby",
                    "writePolicy": "WriteBack",
                    "pool": "default-pool",
                    "redundancyOverlap": 1,
                    "reclaimPolicy": "Retain",
                    "serverAffinity": {
                        "autoFailback": "Enabled"
                    },
                    "compress": {
                        "algorithm": "None"
                    },
                    "ECfragmentSize": 16
                },
                "dataHealth": {
                    "normal": 100,
                    "lowRedundancy": 0,
                    "error": 0
                },
                "number": 1,
                "WWID": "3300000001892b447"
            }
        ]
    }
}

息壤智算

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

存储资源盘活系统

存储资源盘活系统

请求语法

请求参数

响应结果

请求示例1

响应示例1

请求示例2

响应示例2

活动

息壤智算

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

存储资源盘活系统

存储资源盘活系统

请求语法

请求参数

响应结果

请求示例1

响应示例1

请求示例2

响应示例2