文档中心

缓存数据库 Redis 版

实例管理

DescribeDBInstances

调用 DescribeDBInstances 接口查询 Redis 实例的基本信息。

请求类型

同步请求。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

参数	类型	是否必选	示例值	描述
RegionId	String	否	cn-beijing	实例所属的地域 ID。说明若该参数留空，默认使用签名中设置的地域进行筛选。关于签名机制的更多信息，请参见签名机制。您可以调用 DescribeRegions接口查询 Redis 实例支持的所有地域信息，包括地域 ID。
PageNumber	Integer	否	1	实例信息列表的页码。取值为不超过 Integer 数据类型的最大值，起始值与默认值均为 1。
PageSize	Integer	否	10	每页记录数。取值为 1~1000 间的整数，默认值为 10。
ZoneId	String	否	cn-beijing-a	实例所属的可用区 ID，支持模糊查询。说明您可以调用 DescribeZones接口查询 Redis 实例在指定地域下的可用区资源信息，包括可用区 ID。
InstanceId	String	否	redis-cn0212gzmh2xsh2xs	实例 ID，精确查询。说明若该参数留空，表示不使用实例 ID 条件进行筛选。
InstanceName	String	否	api_test	实例名称，支持模糊查询。说明若该参数留空，表示不使用实例名称条件进行筛选。
ShardedCluster	Integer	否	1	实例是否启用分片集群。取值范围如下： 0：不启用。 1：启用。说明若该参数留空，表示不使用实例是否启用分片集群条件进行筛选。
Status	String	否	Running	实例状态。关于实例状态的更多详情，请参见实例状态。说明若该参数留空，表示不使用实例状态条件进行筛选。
EngineVersion	String	否	5.0	实例的数据库版本号。取值范围如下： 5.0 6.0 7.0 说明若该参数留空，表示不使用实例的数据库版本号条件进行筛选。
VpcId	String	否	vpc-rs5811nceqyov0xov0x	实例所属的私有网络（VPC）ID。支持模糊查询。说明若该参数留空，表示不使用实例的私有网络 ID 条件进行筛选。您可以调用 DescribeVpcs接口查询当前账号下的所有私有网络列表信息，包括私有网络 ID。
ChargeType	String	否	PostPaid	实例的计费类型。取值范围如下： PostPaid：按量计费。 PrePaid：包年包月。说明若该参数留空，表示不使用实例的计费类型条件进行筛选。关于计费类型的更多信息，请参见计费类型。
TagFilters	Array of TagFilter	否	请参见请求示例。	用于查询筛选的标签键值对数组。说明若该参数留空，表示不使用标签条件进行筛选。
ProjectName	String	否	default	实例所属的项目名称。说明若该参数留空，表示不使用实例的项目名称条件进行筛选。
ServiceType	String	否	Basic	实例的服务类型，取值范围如下： Basic（默认值）：社区版。 Enterprise：企业版。
DataLayout	String	否	RAM	实例的数据存储形态。说明该参数仅对企业版（即ServiceType为Enterprise）实例有意义；社区版（即ServiceType为Basic）实例不涉及数据存储形态，DataLayout取值固定为RAM。若该参数留空，表示不使用数据存储形态进行筛选。

TagFilter

参数	类型	是否必选	示例值	描述
Key	String	是	department	用于查询筛选的标签键。说明当需要使用标签对查询结果进行筛选时，标签键（Key）必填，标签值（Value）可不填，不填标签值表示不对标签值作限制，会搜索所有绑定了指定标签键的实例。单次最多支持同时传入 10 组标签键值对进行查询筛选。允许传入重复的标签键。
Value	String	否	game	用于查询筛选的标签键所对应的标签值。说明若该参数留空，表示不对标签值作限制，会筛选所有绑定了指定标签键的实例。若传入空字符串，表示筛选对应标签键下，标签值为空的实例。

返回参数

参数	类型	示例值	描述
TotalInstancesNum	Integer	1	符合查询条件的实例数量。
Instances	Array of Instances	请参见返回示例。	实例基本信息列表。

Instances

参数	类型	示例值	描述
BlueGreenRole	String	Blue	实例的蓝绿部署角色。取值范围如下： Blue：蓝色实例。 Green：绿色实例。说明仅使用过蓝绿部署功能的 Redis 实例会返回该参数。更多详情，请参见通过蓝绿部署升级大版本。
Capacity	Object of InstanceCapacity	请参见返回示例。	实例的容量信息。
ChargeType	String	PrePaid	计费类型，取值范围如下： PostPaid：按量计费。 PrePaid：包年包月。说明关于计费类型的更多信息，请参见计费类型。
CreateTime	String	2024-04-30T14:24:32Z	实例的创建时间，格式为 yyyy-MM-ddTHH:mm:ssZ（UTC）。
DataLayout	String	RAM	实例的数据存储形态。说明该参数仅对企业版（即 ServiceType 为 Enterprise）实例有意义；社区版（即 ServiceType 为 Basic）实例不涉及数据存储形态，DataLayout 返回值固定为 RAM。
DeletionProtection	String	enabled	实例的删除保护功能状态。取值范围如下： enabled：开启。 disabled：关闭。说明关于删除保护功能的更多信息，请参见实例删除保护。
EngineVersion	String	5.0	实例的数据库版本。
ExpiredTime	String	2024-09-01 23:59:59	实例到期时间，格式为 yyyy-MM-dd HH:mm:ss（UTC+8）。说明仅包年包月实例（即 ChargeType 为 PrePaid），会返回该参数。
InstanceId	String	redis-cn0212gzmh2xs****	实例 ID。
InstanceName	String	test	实例名称。
InstanceClass	String	PrimarySecondary	实例类型。取值范围如下： PrimarySecondary：主备实例。 Standalone：单节点实例。说明关于实例类型的更多说明，请参见产品架构。
MultiAZ	String	disabled	实例的可用区部署方案。取值范围如下： enabled：多可用区部署方案。 disabled：单可用区部署方案。说明关于可用区部署方案的更多说明，请参见多可用区同城容灾解决方案。
NodeNumber	Integer	2	每个分片中的节点数。
PrivateAddress	String	redis-cngzxq26qdwpk****.redis.cn-guangzhou.ivolces.com	实例私网连接地址的域名。
ProjectName	String	default	实例所属的项目名称。
RegionId	String	cn-beijing	实例所属地域的地域 ID。
ShardCapacity	Double	2	每个分片的内存容量。单位：GiB。
ShardedCluster	Integer	1	当前实例是否已启用分片集群，取值范围如下： 0：不启用（即实例中仅包含了 1 个分片）。 1：启用（即实例中包含了 1 个以上的分片）。
ShardNumber	Integer	2	实例中的分片数。
ServiceType	String	Basic	实例的服务类型。取值范围如下： Basic：社区版。 Enterprise：企业版。
Status	String	Running	实例状态。关于实例状态的更多详情，请参见实例状态。
Tags	Array of Tag		实例已绑定的标签信息。说明仅已绑定了标签的实例才会返回该参数。
VIP	String	192.168..	实例私网连接地址所对应的 IPv4 地址。
VIPv6	String	2408:1000:abe5:ff40:a189:2f34:a82e:****	实例私网连接地址所对应的 IPv6 地址。说明仅当实例使用了 IPv6 地址时才会返回该参数。
VpcId	String	vpc-rs5811nceqyov0x58x4****	实例的私有网络 ID。
ZoneIds	Array of String	["cn-beijing-a"]	实例所在的可用区列表。
PrivatePort	String	6379	实例私网连接地址的端口号。

InstanceCapacity

参数	类型	示例值	描述
Used	Long	100	当前实例已用容量。单位：MiB。
Total	Long	36864	当前实例的内存总容量。单位：MiB。

Tag

参数	类型	示例值	描述
Key	String	department	当前实例所绑定标签的标签键。
Value	String	game	当前实例所绑定标签的标签值。

示例

请求示例

POST https://redis.cn-beijing.volcengineapi.com/?Action=DescribeDBInstances&Version=2020-12-07 HTTP/1.1​
Host: redis.cn-beijing.volcengineapi.com​
Content-Type: application/json; charset=utf-8​
X-Date: 20201103T104027Z​
Authorization: HMAC-SHA256 Credential=AK****/20201103/cn-beijing/Redis/request,SignedHeaders=content-type;host;x-date,Signature=****​
{​
	"RegionId": "cn-beijing",​
	"PageNumber": 1,​
	"PageSize": 10,​
	"ServiceType":"Basic"​
}​

返回示例

{​
    "ResponseMetadata": {​
        "RequestId": "202204151542080102120420191760****",​
        "Action": "DescribeDBInstances",​
        "Version": "2020-12-07",​
        "Service": "Redis",​
        "Region": "cn-beijing"​
    },​
    "Result": {​
        "Instances": [​
            {​
                "Capacity": {​
                    "Total": 2048,​
                    "Used": 57​
                },​
                "ChargeType": "PostPaid",​
                "CreateTime": "2024-04-30T14:24:32Z",                "DeletionProtection": "disabled",​
                "EngineVersion": "5.0",​
                "ExpiredTime": "",​
                "InstanceClass": "PrimarySecondary",​
                "InstanceId": "redis-cn0212gzmh2xs****",​
                "InstanceName": "test",​
                "NodeNumber": 2,​
                "ProjectName": "default",​
                "MultiAZ": "disabled",​
                "RegionId": "cn-beijing",​
                "ShardCapacity": 1,​
                "ShardNumber": 2,​
                "ShardedCluster": 1,​
                "Status": "Running",​
                "Tags": [​
                    {​
                        "Key": "owner",​
                        "Value": "Alice"​
                    },​
                    {​
                        "Key": "department",​
                        "Value": "game"​
                    }​
                ],​
                "VpcId": "vpc-rs5811nceqyov0x58x4****",​
                "ZoneIds": [​
                    "cn-beijing-a"​
                ],​
                "DataLayout": "RAM",​
                "PrivateAddress": "redis-cn0212gzmh2xs****.redis.ivolces.com",​
                "PrivatePort": "6379",​
                "VIP": "192.168.***.***",​
                "VIPv6": "2408:1000:abe5:ff40:a189:2f34:a82e:****"​
            }​
        ],​
        "TotalInstancesNum": 1​
    },​
    "BlueGreenRole": "Blue"​
}​

错误码

更多详情，请参见错误码。

最近更新时间：2026.09.21 14:23:30

这个页面对您有帮助吗？

有用

无用