# 查询子网资源实例 - ListSubnetsByTags
#### 功能介绍
使用标签过滤实例。
#### 调试
您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=VPC&version=v2&api=ListSubnetsByTags)中调试该接口。
#### 授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。
- 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-vpc/vpc_permission_0000.html)。
- 如果使用身份策略授权，需具备如下身份策略权限。
  
  | 授权项                  | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名                                                                                                                         | 依赖的授权项 |
  |:---|:---|:---|:---|:---|:---|
  | vpc:subnets:listTags | List | subnet \*   | -   | - vpc:subnetTags:get   | -      |
     
  
 
#### URI
POST /v2.0/{project_id}/subnets/resource_instances/action
参数说明请参见[表1]。
 表1参数说明 
| 名称         | 是否必选 | 说明                                                                           |
|:---|:---|:---|
| project_id | 是    | 项目ID，请参见[获取项目ID](https://support.huaweicloud.com/api-vpc/vpc_api_0011.html)。 |
   
#### 请求参数
表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为匹配的值。此字段为固定字典值。                                                                        |
   
 表3tag字段数据结构说明 
| 名称     | 是否必选 | 参数类型             | 说明                                                               |
|:---|:---|:---|:---|
| key    | 是    | String           | 键。最大长度128个unicode字符。 key不能为空。(搜索时不对此参数做校验)                       |
| values | 是    | Array of strings | 值列表。每个值最大长度255个unicode字符，如果values为空列表，则表示any_value。value之间为或的关系。 |
   
 表4match字段数据结构说明 
| 名称    | 是否必选 | 参数类型   | 说明                                                                                                          |
|:---|:---|:---|:---|
| 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                                                             | 总记录数                                                          |
   
 表6resource对象 
| 名称              | 参数类型                                                         | 说明                                                           |
|:---|:---|:---|
| resource_id     | String                                                       | 资源ID                                                         |
| resource_detail | Object                                                       | 资源详情。 资源对象，用于扩展。默认为空                                         |
| tags            | Array of [tag] objects | 标签列表，没有标签默认为空数组，参见[表7] |
| resource_name   | String                                                       | 资源名称，没有默认为空字符串                                               |
   
 表7tag字段数据结构说明 
| 名称    | 是否必选 | 参数类型   | 说明                                                               |
|:---|:---|:---|:---|
| 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": "resource1", 
              "tags": [
                  {
                     "key": "key1",
                     "value": "value1"
                  },
                  {
                     "key": "key2",
                     "value": "value2"
                  }
               ]
           }
         ], 
        "total_count": 1000
  }
  ```
  

- action为count
  ```
  {
         "total_count": 1000
  }
  ```
  
 
#### 状态码
请参见[状态码](https://support.huaweicloud.com/api-vpc/vpc_api_0002.html)。
#### 错误码
请参考[错误码](https://support.huaweicloud.com/api-vpc/vpc_api_0003.html)。