文档首页/ 云堡垒机 CBH/ API参考/ API说明/ 标签管理/ 使用标签过滤实例 - ListInstancesByTag

更新时间：2025-10-23 GMT+08:00

在线调试

CLI示例

查看PDF

使用标签过滤实例 - ListInstancesByTag

功能介绍

使用标签过滤实例。

调用方法

请参见如何调用API。

URI

POST /v2/{project_id}/cbs/instance/filter

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。获取方法请参见获取项目ID。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。获取方法请参见获取用户Token。
limit	否	String	查询记录数（action为count时无此参数）如果action为filter默认为1000，limit最多为1000,不能为负数，最小值为1。
offset	否	String	索引位置，偏移量（action为count时无此参数）从第一条数据偏移offset条数据后开始查询，如果action为filter默认为0（偏移0条数据，表示从第一条数据开始查询）,必须为数字，不能为负数。

表3 请求Body参数
参数	是否必选	参数类型	描述
without_any_tag	否	Boolean	不包含任意一个标签，该字段为true时查询所有不带标签的资源。此时忽略 “tags”、“tags_any”、“not_tags”、“not_tags_any”字段。
tags	否	Array of Tags objects	包含标签，最多包含50个key，每个key下面的value最多10个，每个key对应的value可以为空数组但结构体不能缺失。 Key不能重复，同一个key中values不能重复。结果返回包含所有标签的资源列表，key之间是与的关系， key-value结构中value是或的关系。无tag过滤条件时返回全量数据。
tags_any	否	Array of Tags objects	包含任意标签，最多包含50个key，每个key下面的value最多10个,每个key对应的value可以为空数组但结构体不能缺失。Key不能重复，同一个key中values不能重复。结果返回包含标签的资源列表，key之间是或的关系，key-value结构中value是或的关系。无过滤条件时返回全量数据。
not_tags	否	Array of Tags objects	不包含标签，最多包含50个key，每个key下面的value最多10个, 每个key对应的value可以为空数组但结构体不能缺失。Key不能重复，同一个key中values不能重复。结果返回不包含标签的资源列表，key之间是与的关系，key-value结构中value是或的关系。无过滤条件时返回全量数据。
not_tags_any	否	Array of Tags objects	不包含任意标签，最多包含50个key，每个key下面的value最多10个, 每个key对应的value可以为空数组但结构体不能缺失。Key不能重复，同一个key中values不能重复。结果返回不包含标签的资源列表，key之间是或的关系，key-value结构中value是或的关系。无过滤条件时返回全量数据。
sys_tags	否	Array of Tags objects	仅op_service权限可以使用此字段做资源实例过滤条件。目前TMS调用时只包含一个tag结构体。 key：_sys_enterprise_project_id value：企业项目id列表目前TMS调用时，key下面只包含一个value。0表示默认企业项目 sys_tags和租户标签过滤条件（without_any_tag 、tags、tags_any、not_tags、not_tags_any）不能同时使用无sys_tags时按照tag接口处理，无tag过滤条件时返回全量数据。
matches	否	Array of Match objects	搜索字段，key为要匹配的字段，如resource_name等。 value为匹配的值。key为固定字典值，不能包含重复的key或不支持的key。根据key的值确认是否需要模糊匹配，如resource_name默认为模糊搜索（不区分大小写），如果value为空字符串精确匹配（多数服务不存在资源名称为空的情况，因此此类情况返回空列表）。 resource_id为精确匹配。第一期只做resource_name，后续再扩展。

表4 Tags
参数	是否必选	参数类型	描述
key	是	String	键。说明：说明： key不能为空，长度1~128个字符（中文也可以输入128个字符）可用 UTF-8 格式表示的字母(包含中文)、数字和空格，以及以下字符： _ . : = + - @ sys_开头属于系统标签，租户不能输入建议正则：^((?!sys)[\p{L}\p{Z}\p{N}.:=+\-@]*)$
values	是	Array of strings	值列表。说明：说明：长度0~255个字符（中文也可以输入255个字符）可用 UTF-8 格式表示的字母(包含中文)、数字和空格，以及以下字符： _ . : / = + - @ 建议正则：^([\p{L}\p{Z}\p{N}_.:/=+-@]*)$ 资源标签值可以为空（empty or null）预定义标签值不可以为空

表5 Match
参数	是否必选	参数类型	描述
key	是	String	键。第一期限定为resource_name，后续扩展。
value	是	String	值。每个值最大长度255个unicode字符。不校验字符集范。

响应参数

状态码：200

表6 响应Body参数
参数	参数类型	描述
resources	Array of Resources objects	根据查询模式获取到的资源实例详情。
total_count	Integer	总记录数。

表7 Resources
参数	参数类型	描述
resource_id	String	实例ID。
resource_detail	InstanceDetail object	CBH实例详情
tags	Array of ResourceTag objects	tags。
sys_tags	Array of ResourceTag objects	sys_tags。
resource_name	String	资源名称。

表8 InstanceDetail
参数	参数类型	描述
name	String	云堡垒机实例名称。
server_id	String	云堡垒机服务器id。
instance_id	String	云堡垒机实例id。
alter_permit	Boolean	云堡垒机实例是否可以扩容。 true：是 false：否
enterprise_project_id	String	项目ID。
period_num	String	云堡垒机实例订购周期数。
start_time	String	云堡垒机实例开始时间，使用时间戳格式表示。
end_time	String	云堡垒机实例结束时间，使用时间戳格式表示。
created_time	String	云堡垒机实例创建时间，使用UTC时间表示。
upgrade_time	Long	云堡垒机实例升级定时时间，使用时间戳格式表示。
update	String	云堡垒机实例是否可以升级。 OLD：当前已是最新版本 NEW：可以升级小版本 CROSS_OS：可以跨版本升级 ROLLBACK：可以回滚
bastion_version	String	云堡垒机实例当前版本。
az_info	az_info object	可用区信息。
status_info	status_info object	状态信息。
resource_info	resource_info object	资源信息。
network	network object	网络信息。
ha_info	ha_info object	主备信息。

表9 az_info
参数	参数类型	描述
region	String	云堡垒机实例所在可用区ID。
zone	String	云堡垒机实例所在可用分区ID。(实例为主备模式时作为主机实例所在可用分区)
availability_zone_display	String	云堡垒机实例所在可用分区中文名称。(实例为主备模式时作为主机实例所在可用分区中文名称)
slave_zone	String	云堡垒机备机实例所在可用区。
slave_zone_display	String	云堡垒机备机实例所在可用区中文名称。

**表10** status_info
参数	参数类型	描述
status	String	云堡垒机实例状态。 SHUTOFF：已关闭 ACTIVE：运行中 DELETING：删除中 BUILD：创建中 DELETED：已删除 ERROR：故障 HAWAIT：等待备机创建成功 FROZEN：已冻结 UPGRADING：升级中 UNPAID：待支付 RESIZE：规格变更中 DILATATION：扩容中 HA：配置HA中
task_status	String	云堡垒机实例当前的任务状态。 powering-on：开启 powering-off：关闭 rebooting：重启 delete_wait：删除 frozen：冻结 NO_TASK：运行 unfrozen：解冻 alter：变更 updating：升级中 configuring-ha：配置HA data-migrating：数据迁移中 rollback：版本回滚中 traffic-switchover：流量切换中
create_instance_status	String	云堡垒机实例在创建实例过程中的状态信息。 Waiting for payment：等待支付 creating-network：创建网络 creating-server：创建服务 tranfering-horizontal-network：网络打通 adding-policy-route：添加路由策略 configing-dns：配置DNS starting-cbs-service：服务运行中 setting-init-conf：初始化 buying-EIP：购买弹性公网IP
instance_status	String	云堡垒机实例状态。 building：创建中 deleting：删除中 deleted：删除了 unpaid：未支付 upgrading：升级中 resizing：扩容中 abnormal：异常 error：故障 ok：正常
instance_description	String	云堡垒机实例信息描述。
fail_reason	String	云堡垒机实例创建实例失败原因。

**表11** resource_info
参数	参数类型	描述
specification	String	云堡垒机实例规格。
order_id	String	订单id。
resource_id	String	云堡垒机实例的资源id，UUID格式显示。
data_disk_size	Long	云堡垒机实例数据盘大小，单位TB。
disk_resource_id	Array of strings	云堡垒机实例数据盘资源ID。

**表12** network
参数	参数类型	描述
vip	String	云堡垒机实例浮动ip。(实例为主备模式时返回对应的值)
web_port	String	云堡垒机实例WEB界面访问的端口号。
public_ip	String	云堡垒机实例弹性公网IP。
public_id	String	云堡垒机实例绑定公网的弹性IP的ID，UUID格式表示。
private_ip	String	云堡垒机实例私有ip。
vpc_id	String	云堡垒机实例所在虚拟私有云ID。
subnet_id	String	云堡垒机实例所在子网ID。
security_group_id	String	云堡垒机实例所属的安全组ID。

**表13** ha_info
参数	参数类型	描述
ha_id	String	主备ID。
instance_type	String	实例类型。 master：主 slave：备

**表14** ResourceTag
参数	参数类型	描述
key	String	键。最大长度128个字符。
value	String	值。每个值最大长度255个字符。

状态码：400

**表15** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_description	String	请求参数错误。

状态码：401

**表16** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_description	String	校验TOKEN失败。

状态码：403

**表17** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_description	String	租户无权限操作。

状态码：404

**表18** 响应Body参数
参数	参数类型	描述
error_code	String	错误码
error_description	String	没有找到CBH资源。

请求示例

{
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ],
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "*value1", "value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "*value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "sys_tags" : [ {
    "key" : "_sys_enterprise_project_id",
    "values" : [ "5aa119a8-d25b-45a7-8d1b-88e127885635" ]
  } ]
}

响应示例

状态码：200

List CBH ByTags Success

{
  "resources" : [ {
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "resouece1",
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ],
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "5aa119a8-xxxx-45a7-xxxx-88e12788xxxx"
    } ]
  } ],
  "total_count" : 1000
}

状态码

状态码	描述
200	List CBH ByTags Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	系统异常

错误码

请参见错误码。

父主题： 标签管理

上一篇：统计符合标签条件的实例数量 - CountInstancesByTag

下一篇：操作堡垒机实例资源标签 - BatchCreateInstanceTag

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消