Querying Ports¶
Function¶
Queries all networks accessible to the tenant submitting the request.
URI¶
GET /v2.0/ports
Example:
GET https://{Endpoint}/v2.0/ports?id={port_id}&name={port_name}&admin_state_up={is_admin_status_up}&network_id={network_id}&mac_address={port_mac}&device_id={port_device_id}&device_owner={device_owner}&tenant_id={tenant_id}&status={port_status}&fixed_ips=ip_address={ip_address}&fixed_ips=subnet_id={subnet_id}
Example of querying ports by page
GET https://{Endpoint}/v2.0/ports?limit=2&marker=791870bd-36a7-4d9b-b015-a78e9b06af08&page_reverse=False
Table 1 describes the parameters.
Name | Mandatory | Type | Description |
---|---|---|---|
id | No | String | Specifies that the port ID is used as the filtering condition. |
name | No | String | Specifies that the port name is used as the filtering condition. |
admin_state_up | No | Boolean | Specifies that the admin state is used as the filtering condition. The value can be true or false. |
network_id | No | String | Specifies that the network ID is used as the filtering condition. |
mac_address | No | String | Specifies that the MAC address is used as the filtering condition. |
device_id | No | String | Specifies that the device ID is used as the filtering condition. |
device_owner | No | String | Specifies that the device owner is used as the filtering condition. |
status | No | String | Specifies that the port status is used as the filtering condition. The value can be ACTIVE, BUILD, or DOWN. |
security_groups | No | Array of strings | Specifies that the ID of the security group is used as the filtering condition. |
fixed_ips | No | Array of strings | Specifies that the IP address is used as the filtering condition. The value can be fixed_ips=ip_address or fixed_ips=subnet_id. |
tenant_id | No | String | Specifies that the project ID is used as the filtering condition. |
marker | No | String | Specifies a resource ID for pagination query, indicating that the query starts from the next record of the specified resource ID. This parameter can work together with the parameter limit.
|
limit | No | Integer | Specifies the number of records that will be returned on each page. The value is from 0 to intmax (2^31-1). The default value is 2000. limit can be used together with marker. For details, see the parameter description of marker. |
Request Message¶
None
Example Request¶
Example 1
GET https://{Endpoint}/v2.0/ports?limit=1
Example 2
GET https://{Endpoint}/v2.0/ports?mac_address=fa:16:3e:f1:0b:09
Example 3
GET https://{Endpoint}/v2.0/ports?admin_state_up=False
Example 4
GET https://{Endpoint}/v2.0/ports?device_id=e6c05704-c907-4cc1-8106-69b0996c43b9
Example 5
GET https://{Endpoint}/v2.0/ports?tenant_id=6c9298ec8c874f7f99688489ab65f90e&name=port_vm_50_3
Example 6
GET https://{Endpoint}/v2.0/ports?name=port_vm_50_3
Response Parameter¶
Parameter | Type | Description |
---|---|---|
ports | Array of port objects | Specifies the port object list. For details, see Table 3. |
ports_links | Array of ports_link objects | Specifies the pagination information. For details, see Table 9. Only when limit is used for filtering and the number of resources exceeds the value of limit or 2000 (default value of limit), value next will be returned for rel and a link for href. |
Attribute | Type | Description |
---|---|---|
id | String | Specifies the port ID. A maximum of 255 characters are allowed. This parameter is not mandatory when you query ports. |
name | String | Specifies the port name. |
network_id | String | Specifies the ID of the network to which the port belongs. |
admin_state_up | Boolean | Specifies the administrative status. The default value is true. |
mac_address | String | Specifies the port MAC address. For example, "mac_address": "fa:16:3e:9e:ff:55". This value can only be dynamically assigned by the system. |
fixed_ips | Array of fixed_ip objects | Specifies the port IP address. For details, see Table 4. For example, the value is "fixed_ips": [{"subnet_id": "4dc70db6-cb7f-4200-9790-a6a910776bba", "ip_address": "192.169.25.79"}]. |
device_id | String | Specifies the device ID. This value is automatically maintained by the system and cannot be set or updated manually. The port with this field specified cannot be deleted. |
device_owner | String | Specifies the DHCP, router or Nova to which a device belongs. The value can be network:dhcp, network:router_interface_distributed, compute:xxx, or neutron:VIP_PORT. (In value compute:xxx, xxx specifies the AZ name, for example, compute:aa-bb-cc indicates that the private IP address is used by an ECS in the aa-bb-cc AZ). This parameter value cannot be updated. You can only set device_owner to neutron:VIP_PORT for a virtual IP address port during port creation. If this parameter of a port is not left blank, the port can only be deleted when this parameter value is neutron:VIP_PORT. The port with this field specified cannot be deleted. |
tenant_id | String | Specifies the project ID. |
status | String | Specifies the port status. The value can be ACTIVE, BUILD, or DOWN. |
security_groups | Array of strings | Specifies the UUID of the security group, for example, "security_groups": ["a0608cbf-d047-4f54-8b28-cd7b59853fff"]. This is an extended attribute. This parameter cannot be left blank. |
allowed_address_pairs | Array of allow_address_pair objects | Specifies the IP address and MAC address pair. This is an extended attribute. For details, see Table 5. Instructions:
|
extra_dhcp_opts | Array of extra_dhcp_opt objects | Specifies the extended DHCP option. This is an extended attribute. For details, see Table 6. |
binding:vif_details | binding:vif_details object | For details, see Table 7. |
binding:profile | Object | Specifies the user-defined settings. This is an extended attribute. Instructions:
|
binding:vnic_type | String | Specifies the type of the bound vNIC. normal: Softswitch |
port_security_enabled | Boolean | Specifies whether the security option is enabled for the port. If the option is not enabled, the security group and DHCP snooping do not take effect. |
dns_assignment | Array of dns_assignment objects | Specifies the default private network domain name information of the primary NIC. This is an extended attribute. The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.
|
dns_name | String | Specifies the default private network DNS name of the primary NIC. This is an extended attribute. The system automatically sets this parameter, and you are not allowed to configure or change the parameter value. Before accessing the default private network domain name, ensure that the subnet uses the DNS provided by the current system. |
project_id | String | Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID. |
created_at | String | Specifies the time (UTC) when the port is created. Format: yyyy-MM-ddTHH:mm:ss |
updated_at | String | Specifies the time (UTC) when the port is updated. Format: yyyy-MM-ddTHH:mm:ss |
Attribute | Type | Description |
---|---|---|
subnet_id | String | Specifies the ID of the subnet to which the port belongs. This parameter cannot be updated. |
ip_address | String | Specifies the port IP address. This parameter cannot be updated. |
Name | Mandatory | Type | Description |
---|---|---|---|
ip_address | Yes | String |
|
mac_address | No | String | Specifies the MAC address. |
Attribute | Type | Description |
---|---|---|
opt_name | String | Specifies the option name. |
opt_value | String | Specifies the option value. |
Name | Type | Description |
---|---|---|
primary_interface | Boolean | If the value is true, this is the primary NIC. |
port_filter | Boolean | Specifies the port used for filtering in security groups to protect against MAC or IP spoofing. |
ovs_hybrid_plug | Boolean | Specifies that OVS hybrid plug should be used by Nova APIs. |
Important
The binding:vif_details object may include more response parameters (such as port_filter and ovs_hybrid_plug).
Name | Type | Description |
---|---|---|
hostname | String | Specifies the host name of the port. |
ip_address | String | Specifies the port IP address. |
fqdn | String | Specifies the private network fully qualified domain name (FQDN) of the port. |
Name | Type | Description |
---|---|---|
href | String | Specifies the API link. |
rel | String | Specifies the relationship between the API link and the API version. |
Example Response¶
Example 1
{
"ports": [{
"id": "791870bd-36a7-4d9b-b015-a78e9b06af08",
"name": "port-test",
"status": "DOWN",
"admin_state_up": true,
"fixed_ips": [],
"mac_address": "fa:16:3e:01:e0:b2",
"network_id": "00ae08c5-f727-49ab-ad4b-b069398aa171",
"tenant_id": "db82c9e1415a464ea68048baa8acc6b8",
"project_id": "db82c9e1415a464ea68048baa8acc6b8",
"device_id": "",
"device_owner": "",
"security_groups": ["d0d58aa9-cda9-414c-9c52-6c3daf8534e6"],
"extra_dhcp_opts": [],
"allowed_address_pairs": [],
"binding:vnic_type": "normal",
"binding:vif_details": {},
"binding:profile": {},
"port_security_enabled": true,
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41"
}],
"ports_links": [
{
"rel": "next",
"href": "https://{Endpoint}/v2.0/ports?limit=1&marker=791870bd-36a7-4d9b-b015-a78e9b06af08"
},
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?limit=1&marker=791870bd-36a7-4d9b-b015-a78e9b06af08&page_reverse=True"
}
]
}
Example 2
{
"ports": [
{
"admin_state_up": true,
"allowed_address_pairs": [],
"binding:vnic_type": "normal",
"device_id": "e6c05704-c907-4cc1-8106-69b0996c43b9",
"device_owner": "compute:az3.dc1",
"port_security_enabled":true,
"extra_dhcp_opts": [],
"fixed_ips": [
{
"ip_address": "172.16.0.37",
"subnet_id": "b3ac1347-63f2-4e82-b853-3d86416a0db5"
}
],
"dns_assignment": [
{
"hostname": "ip-172-16-0-37",
"ip_address": "172.16.0.37",
"fqdn": "ip-172-16-0-37.xxx.compute.internal."
}
],
"dns_name": "ip-172-16-0-37",
"id": "7bb64706-6e46-4f94-a28a-4bc7caaab87d",
"mac_address": "fa:16:3e:f1:0b:09",
"name": "port_vm_50_3",
"network_id": "a54e1b19-ce78-4b7e-b28b-d2d716cdc161",
"security_groups": [
"ef69bc60-2f4b-4f97-b95b-e3b68df0c0b2"
],
"status": "ACTIVE",
"tenant_id": "6c9298ec8c874f7f99688489ab65f90e",
"project_id": "6c9298ec8c874f7f99688489ab65f90e",
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41"
}
],
"ports_links": [
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?mac_address=fa%3A16%3A3e%3Af1%3A0b%3A09&marker=7bb64706-6e46-4f94-a28a-4bc7caaab87d&page_reverse=True"
}
]
}
Example 3
{
"ports": [
{
"admin_state_up": false,
"allowed_address_pairs": [],
"binding:vnic_type": "normal",
"device_id": "",
"device_owner": "",
"port_security_enabled":true,
"extra_dhcp_opts": [],
"fixed_ips": [
{
"ip_address": "10.100.100.62",
"subnet_id": "9b28f20c-0234-419f-a0b4-4a84f182f64b"
}
],
"dns_name": "",
"id": "ffc0bdee-8413-4fa2-bd82-fa8efe5b3a87",
"mac_address": "fa:16:3e:2b:bc:57",
"name": "small_net_port",
"network_id": "b299b151-7a66-4c6f-a313-cdd3b5724296",
"security_groups": [
"ef69bc60-2f4b-4f97-b95b-e3b68df0c0b2"
],
"status": "DOWN",
"tenant_id": "6c9298ec8c874f7f99688489ab65f90e",
"project_id": "6c9298ec8c874f7f99688489ab65f90e",
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41"
}
],
"ports_links": [
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?admin_state_up=False&marker=ffc0bdee-8413-4fa2-bd82-fa8efe5b3a87&page_reverse=True"
}
]
}
Example 4
{
"ports": [
{
"admin_state_up": true,
"allowed_address_pairs": [],
"binding:vnic_type": "normal",
"device_id": "e6c05704-c907-4cc1-8106-69b0996c43b9",
"device_owner": "compute:az3.dc1",
"port_security_enabled":true,
"extra_dhcp_opts": [],
"fixed_ips": [
{
"ip_address": "10.1.0.37",
"subnet_id": "b3ac1347-63f2-4e82-b853-3d86416a0db5"
}
],
"dns_assignment": [
{
"hostname": "ip-10-1-0-37",
"ip_address": "10.1.0.37",
"fqdn": "ip-10-1-0-37.xxx.compute.internal."//xxx indicates the region name.
}
],
"dns_name": "ip-10-1-0-37",
"id": "7bb64706-6e46-4f94-a28a-4bc7caaab87d",
"mac_address": "fa:16:3e:f1:0b:09",
"name": "port_vm_50_3",
"network_id": "a54e1b19-ce78-4b7e-b28b-d2d716cdc161",
"security_groups": [
"ef69bc60-2f4b-4f97-b95b-e3b68df0c0b2"
],
"status": "ACTIVE",
"tenant_id": "6c9298ec8c874f7f99688489ab65f90e",
"project_id": "6c9298ec8c874f7f99688489ab65f90e" ,
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41"
}
],
"ports_links": [
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?device_id=77307088-ae60-49fb-9146-924dcf1d1402&marker=7bb64706-6e46-4f94-a28a-4bc7caaab87d&page_reverse=True"
}
]
}
Example 5
{
"ports": [
{
"admin_state_up": true,
"allowed_address_pairs": [],
"binding:vnic_type": "normal",
"device_id": "e6c05704-c907-4cc1-8106-69b0996c43b9",
"device_owner": "compute:az3.dc1",
"port_secuirty_enabled":true,
"extra_dhcp_opts": [],
"fixed_ips": [
{
"ip_address": "10.1.0.37",
"subnet_id": "b3ac1347-63f2-4e82-b853-3d86416a0db5"
}
],
"dns_assignment": [
{
"hostname": "ip-10-1-0-37",
"ip_address": "10.1.0.37",
"fqdn": "ip-10-1-0-37.xxx.compute.internal."//xxx indicates the region name.
}
],
"dns_name": "ip-10-1-0-37",
"id": "7bb64706-6e46-4f94-a28a-4bc7caaab87d",
"mac_address": "fa:16:3e:f1:0b:09",
"name": "port_vm_50_3",
"network_id": "a54e1b19-ce78-4b7e-b28b-d2d716cdc161",
"security_groups": [
"ef69bc60-2f4b-4f97-b95b-e3b68df0c0b2"
],
"status": "ACTIVE",
"tenant_id": "6c9298ec8c874f7f99688489ab65f90e",
"project_id": "6c9298ec8c874f7f99688489ab65f90e" ,
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41"
}
],
"ports_links": [
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?tenant_id=6c9298ec8c874f7f99688489ab65f90e&name=port_vm_50_3&marker=7bb64706-6e46-4f94-a28a-4bc7caaab87d&page_reverse=True"
}
]
}
Example 6
{
"ports": [
{
"status": "DOWN",
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"device_owner": "",
"port_security_enabled":true,
"fixed_ips": [
{
"subnet_id": "391c74f7-e3b1-405c-8473-2f71a0aec7dc",
"ip_address": "10.1.0.33"
}
],
"dns_name": "",
"id": "0f405555-739f-4a19-abb7-ec11d005b3a9",
"security_groups": [
"043548bc-1020-4be0-885a-caac8530e8f6"
],
"device_id": "",
"port_security_enabled":true,
"name": "port_vm_50_3",
"admin_state_up": true,
"network_id": "9898a82d-7795-4ad5-bf2c-0ed8b822be4f",
"tenant_id": "3e4a1816927f405cacbc3dca1e05111e",
"project_id": "3e4a1816927f405cacbc3dca1e05111e",
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41",
"binding:vnic_type": "normal",
"mac_address": "fa:16:3e:b0:d9:cf"
},
{
"status": "ACTIVE",
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"device_owner": "compute:az3.dc1",
"port_security_enabled":true,
"fixed_ips": [
{
"subnet_id": "b3ac1347-63f2-4e82-b853-3d86416a0db5",
"ip_address": "10.1.0.37"
}
],
"dns_assignment": [
{
"hostname": "ip-10-1-0-37",
"ip_address": "10.1.0.37",
"fqdn": "ip-10-1-0-37.xxx.compute.internal."//xxx indicates the region name.
}
],
"dns_name": "ip-10-1-0-37",
"id": "7bb64706-6e46-4f94-a28a-4bc7caaab87d",
"security_groups": [
"ef69bc60-2f4b-4f97-b95b-e3b68df0c0b2"
],
"device_id": "e6c05704-c907-4cc1-8106-69b0996c43b9",
"name": "port_vm_50_3",
"admin_state_up": true,
"network_id": "a54e1b19-ce78-4b7e-b28b-d2d716cdc161",
"tenant_id": "6c9298ec8c874f7f99688489ab65f90e",
"project_id": "3e4a1816927f405cacbc3dca1e05111e",
"created_at": "2018-09-13T01:43:41",
"updated_at": "2018-09-13T01:43:41",
"binding:vnic_type": "normal",
"binding:vnic_type": "normal",
"mac_address": "fa:16:3e:f1:0b:09"
}
],
"ports_links": [
{ "rel": "previous",
"href": "https://{Endpoint}/v2.0/ports?name=port_vm_50_3&marker=0f405555-739f-4a19-abb7-ec11d005b3a9&page_reverse=True"
}
]
}
Status Code¶
See Status Codes.
Error Code¶
See Error Codes.