# 查询端口列表 - ListPorts
#### 功能介绍
查询端口的列表信息
![](https://support.huaweicloud.com/api-iec/public_sys-resources/note_3.0-zh-cn.png)
端口是将单个设备（如服务器的NIC）连接到网络的连接点。端口还描述了相关的网络配置，例如子网下的私有IP地址以及它的用途，或者虚拟IP地址以及它绑定的公网IP、网卡、带宽等信息。
#### 调试
您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/IEC/doc?api=ListPorts)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
#### 授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-iec/iec_05_0600.html)。
#### URI
GET /v1/ports
表1Query参数 
| 参数              | 是否必选 | 参数类型             | 描述                                                                                                                |
|:---|:---|:---|:---|
| admin_state_up  | 否    | Boolean          | 按照admin_state_up进行过滤 约束：只支持true                                                      |
| device_id       | 否    | String           | 根据设备ID查询端口。                                                                                                       |
| device_owner    | 否    | String           | 根据设备主查询端口。                                                                                                        |
| fixed_ips       | 否    | Array of strings | 根据绑定的IP查询端口。按照fixed_ips=ip_address或者fixed_ips=subnet_id过滤查询，示例：fixed_ips=ip_address=xxx\&fixed_ips=subnet_id=xxxx |
| id              | 否    | String           | 按照端口ID过滤查询                                                                                                        |
| limit           | 否    | Integer          | 查询返回端口列表数量。取值范围：0\~1000。                                                                                          |
| mac_address     | 否    | String           | 根据网卡的mac地址查询端口。                                                                                                   |
| name            | 否    | String           | 按照name过滤查询 取值范围：最大长度不超过255                                                           |
| network_id      | 否    | String           | 子网的neutron的network的ID。                                                                                            |
| offset          | 否    | Integer          | 查询的偏移量。                                                                                                           |
| security_groups | 否    | String           | 根据安全组信息ID查询端口。                                                                                                    |
| status          | 否    | String           | 按照status过滤查询 取值范围：ACTIVE、BUILD、DOWN                                                  |
   
#### 请求参数
表2请求Header参数 
| 参数           | 是否必选 | 参数类型   | 描述                                                                                     |
|:---|:---|:---|:---|
| X-Auth-Token | 是    | String | 用户Token。 通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。 |
   
#### 响应参数
**状态码：200**
表3响应Body参数 
| 参数    | 参数类型                                               | 描述    |
|:---|:---|:---|
| ports | Array of [Port] objects | 端口对象。 |
| count | Integer                                            | 端口数目。 |
   
 表4Port 
| 参数                    | 参数类型                                                                           | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|:---|:---|:---|
| id                    | String                                                                         | 端口唯一标识                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| name                  | String                                                                         | 端口名称 取值：默认为空，最大长度不超过255                                                                                                                                                                                                                                                                                                                                                                                                                               |
| status                | String                                                                         | 端口状态，Hana硬直通虚拟机端口状态总为DOWN 取值范围：ACTIVE、BUILD、DOWN                                                                                                                                                                                                                                                                                                                                                                                                      |
| admin_state_up        | Boolean                                                                        | 管理状态 约束：只支持true，默认为true                                                                                                                                                                                                                                                                                                                                                                                                                               |
| fixed_ips             | Array of [FixedIp] objects                       | 端口IP。 约束：一个端口只支持一个fixed_ip，且不支持更新。                                                                                                                                                                                                                                                                                                                                                                                                                    |
| mac_address           | String                                                                         | 端口MAC地址 约束：由系统分配，不支持指定                                                                                                                                                                                                                                                                                                                                                                                                                                |
| network_id            | String                                                                         | 端口所属网络的ID 约束：必须是存在的网络ID                                                                                                                                                                                                                                                                                                                                                                                                                               |
| device_id             | String                                                                         | 端口所属设备ID 约束：不支持设置和更新，由系统自动维护                                                                                                                                                                                                                                                                                                                                                                                                                          |
| device_owner          | String                                                                         | 设备所属（DHCP/Router/ lb/Nova） 约束：不支持设置和更新，由系统自动维护                                                                                                                                                                                                                                                                                                                                                                                                        |
| security_groups       | Array of strings                                                               | 安全组的UUID(扩展属性)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| extra_dhcp_opts       | Array of [ExtraDhcpOption] objects       | DHCP的扩展属性。                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| allowed_address_pairs | Array of [AllowedAddressPair] objects | - 功能说明：IP/Mac对列表。   - 约束：    IP地址不允许为 "0.0.0.0/0" 如果allowed_address_pairs配置地址池较大的CIDR（掩码小于24位），建议为该port配置一个单独的安全组。 如果allowed_address_pairs的IP地址为"1.1.1.1/0"，表示关闭源目地址检查开关。 |
| site_id               | String                                                                         | 站点ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| dns_assignment        | Array of [DnsAssignment] objects           | 主网卡默认内网域名信息 约束：不支持设置和更新，由系统自动维护                                                                                                                                                                                                                                                                                                                                                                                                                       |
| dns_name              | String                                                                         | 主网卡默认内网DNS名称 约束：不支持设置和更新，由系统自动维护                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ipv6_bandwidth_id     | String                                                                         | IPv6带宽ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| binding:profile       | Object                                                                         | 功能说明：提供用户设置自定义信息(扩展属性)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| binding:vif_details   | [VifDetails] object                           | vif的详细信息。                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
   
 表5FixedIp 
| 参数         | 参数类型   | 描述     |
|:---|:---|:---|
| subnet_id  | String | 所属子网ID |
| ip_address | String | 端口IP地址 |
   
 表6ExtraDhcpOption 
| 参数        | 参数类型   | 描述       |
|:---|:---|:---|
| opt_name  | String | Option名称 |
| opt_value | String | Option值  |
   
 表7AllowedAddressPair 
| 参数          | 参数类型   | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|:---|:---|:---|
| ip_address  | String | - 功能说明：IP地址   - 约束：    IP地址不支持"0.0.0.0/0" 如果allowed_address_pairs配置地址池较大的CIDR（掩码小于24位），建议为该port配置一个单独的安全组。 如果allowed_address_pairs的IP地址为"1.1.1.1/0"，表示关闭源目地址检查开关。 被绑定的边缘实例网卡allowed_address_pairs的IP地址填"1.1.1.1/0"。 |
| mac_address | String | MAC地址                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
   
 表8DnsAssignment 
| 参数         | 参数类型   | 描述         |
|:---|:---|:---|
| fqdn       | String | 端口内网fqdn   |
| hostname   | String | 端口hostname |
| ip_address | String | 端口IP地址     |
   
 表9VifDetails 
| 参数                | 参数类型    | 描述                  |
|:---|:---|:---|
| primary_interface | Boolean | 取值为true，表示是虚拟机的主网卡。 |
   
#### 请求示例
```
GET https://{endpoint}/v1/ports?limit=100&offset=0&fixed_ips=ip_address=172.16.0.1&fixed_ips=subnet_id=671ff701-3dea-4a15-8aeb-58eb179af4b7
```
#### 响应示例
**状态码：200**
OK
```
{
  "ports" : [ {
    "id" : "0ea06f5f-40dc-4136-aae9-08a0cf8fc356",
    "name" : "671ff701-3dea-4a15-8aeb-58eb179af4b7",
    "status" : "DOWN",
    "admin_state_up" : true,
    "fixed_ips" : [ {
      "subnet_id" : "671ff701-3dea-4a15-8aeb-58eb179af4b7",
      "ip_address" : "172.16.0.1"
    } ],
    "mac_address" : "fa:16:3e:af:fc:8d",
    "network_id" : "eef408da-0f0e-4a09-a5f2-9e9c301c0157",
    "device_id" : "cf47d861-f407-4cd9-aa56-11d97201539d",
    "device_owner" : "network:router_interface_distributed",
    "security_groups" : null,
    "extra_dhcp_opts" : [ ],
    "allowed_address_pairs" : [ ],
    "site_id" : "74a75ed3-cfb9-11ea-a0c3-fa1640495574",
    "dns_assignment" : [ ],
    "dns_name" : ""
  } ],
  "count" : 1
}
```
#### 状态码
| 状态码 | 描述 |
|:---|:---|
| 200 | OK |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-iec/ErrorCode.html)。