文档首页/虚拟私有云 VPC/API参考/API V1/V2/子网资源标签管理/查询子网资源实例 - ListSubnetsByTags
更新时间：2025-12-23 GMT+08:00
查看PDF
分享

查询子网资源实例 - ListSubnetsByTags

功能介绍

使用标签过滤实例。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    vpc:subnets:listTags

    List

    subnet *

    -

    • vpc:subnetTags:get

    -

URI

POST /v2.0/{project_id}/subnets/resource_instances/action

参数说明请参见表1。

表1 参数说明

名称

是否必选

说明

project_id

是

项目ID，请参见获取项目ID。

请求参数

表2 请求参数

参数名称

类型

是否必选

说明

tags

Array of tag objects

否

包含标签，最多包含10个key，每个key下面的value最多10个，结构体不能缺失，key不能为空或者空字符串。Key不能重复，同一个key中values不能重复。

limit

Integer

否

查询记录数（action为count时无此参数）如果action为filter默认为1000，limit最多为1000，不能为负数，最小值为1

offset

Integer

否

（索引位置）， 从offset指定的下一条数据开始查询。 查询第一页数据时，不需要传入此参数，查询后续页码数据时，将查询前一页数据时响应体中的值带入此参数（action为count时无此参数）如果action为filter默认为0，必须为数字，不能为负数

action

String

是

操作标识（仅限于filter，count）：filter（过滤），count(查询总条数)

如果是filter就是分页查询，如果是count只需按照条件将总条数返回即可。

matches

Array of match objects

否

搜索字段，key为要匹配的字段，当前仅支持resource_name。value为匹配的值。此字段为固定字典值。

表3 tag字段数据结构说明

名称

是否必选

参数类型

说明

key

是

String

键。最大长度128个unicode字符。 key不能为空。(搜索时不对此参数做校验)

values

是

Array of strings

值列表。每个值最大长度255个unicode字符，如果values为空列表，则表示any_value。value之间为或的关系。

表4 match字段数据结构说明

名称

是否必选

参数类型

说明

key

是

String

键。当前仅限定为resource_name。

最小长度：1

最大长度：128

value

是

String

值。每个值最大长度255个unicode字符。

请求示例

  • 过滤查询子网资源实例，action为filter，从第1条数据开始查询，单次查询最多返回100条，用matches和tags过滤查询。 
    POST https://{Endpoint}/v2.0/{project_id}/subnets/resource_instances/action

{
    "offset": "0",
    "limit": "100",
    "action": "filter",
    "matches": [
        {
            "key": "resource_name",
            "value": "resource1"
        }
    ],
    "tags": [
        {
            "key": "key1",
            "values": [
                "value1",
                "value2"
            ]
        }
    ]
}
  • 过滤计数子网资源实例，action为count，用matches和tags过滤计数。 
    POST https://{Endpoint}/v2.0/{project_id}/subnets/resource_instances/action

{
    "action": "count",
    "tags": [
        {
            "key": "key1",
            "values": [
                "value1",
                "value2"
            ]
        },
        {
            "key": "key2",
            "values": [
                "value1",
                "value2"
            ]
        }
    ],
    "matches": [
        {
            "key": "resource_name",
            "value": "resource1"
        }
    ]
}

响应参数

表5 响应参数

名称

参数类型

说明

resources

Array of resource objects

resource对象列表，请参见表6。

total_count

Integer

总记录数

表6 resource对象

名称

参数类型

说明

resource_id

String

资源ID

resource_detail

Object

资源详情。 资源对象，用于扩展。默认为空

tags

Array of tag objects

标签列表，没有标签默认为空数组，参见表7

resource_name

String

资源名称，没有默认为空字符串

表7 tag字段数据结构说明

名称

是否必选

参数类型

说明

key

是

String

键。最大长度128个unicode字符。 key不能为空。(搜索时不对此参数做校验)

value

是

string

值列表。每个值最大长度255个unicode字符，如果values为空列表，则表示any_value。value之间为或的关系。

响应示例

  • action为filter 
    { 
      "resources": [
         {
            "resource_detail": null, 
            "resource_id": "cdfs_cefs_wesas_12_dsad", 
            "resource_name": "resouece1", 
            "tags": [
                {
                   "key": "key1",
                   "value": "value1"
                },
                {
                   "key": "key2",
                   "value": "value1"
                }
             ]
         }
       ], 
      "total_count": 1000
}
  • action为count 
    {
       "total_count": 1000
}

状态码

请参见状态码。

错误码

请参考错误码。

父主题： 子网资源标签管理