Querying Ports
Function
Queries all ports accessible to the tenant submitting the request. A maximum of 2,000 records can be returned for each query operation. If the number of records exceeds 2,000, the pagination marker will be returned.
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.
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
id |
No |
String |
Specifies the port ID that is used as the filter. |
name |
No |
String |
Specifies the port name that is used as the filter. |
admin_state_up |
No |
Boolean |
|
network_id |
No |
String |
Specifies the network ID that is used as the filter.
NOTE:
To obtain the network ID:
|
mac_address |
No |
String |
Specifies the MAC address that is used as the filter. |
device_id |
No |
String |
Specifies the device ID that is used as the filter. |
device_owner |
No |
String |
Specifies the device owner that is used as the filter. |
status |
No |
String |
|
security_groups |
No |
Array of strings |
Specifies the ID of the security group that is used as the filter. |
fixed_ips |
No |
Array of strings |
Filter by IP address of the port, that is fixed_ips=ip_address={ip_address} or fixed_ips=subnet_id={subnet_id}. Set {ip_address} to an IP address, for example, 192.168.21.22 or 2a07:b980:4030:14::1. Set {subnet_id} to the IPv4 or IPv6 subnet ID, for example, 011fc878-5521-4654-a1ad-f5b0b5820302. |
tenant_id |
No |
String |
Specifies the project ID that is used as the filter. |
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 |
|
name |
String |
Specifies the port name. |
network_id |
String |
Specifies the ID of the network that the port belongs to. |
admin_state_up |
Boolean |
|
mac_address |
String |
|
fixed_ips |
Array of fixed_ip objects |
|
device_id |
String |
|
device_owner |
String |
|
tenant_id |
String |
Specifies the project ID. |
status |
String |
|
security_groups |
Array of strings |
|
allowed_address_pairs |
Array of allowed_address_pairs objects |
|
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 |
|
binding:vnic_type |
String |
|
port_security_enabled |
Boolean |
Specifies whether the security option is enabled for the port. true indicates that security groups can be added and DHCP anti-spoofing is enabled. false indicates that security groups and DHCP anti-spoofing are not applied. |
dns_assignment |
Array of dns_assignment objects |
|
dns_name |
String |
|
project_id |
String |
Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID. |
created_at |
String |
|
updated_at |
String |
|
Attribute |
Type |
Description |
---|---|---|
subnet_id |
String |
|
ip_address |
String |
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
ip_address |
Yes |
String |
|
mac_address |
No |
String |
Specifies the MAC address. By default, the MAC address of the local port is used. |
Attribute |
Type |
Description |
---|---|---|
opt_name |
String |
Specifies the option name. |
opt_value |
String |
Specifies the option value. |
Parameter |
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. |
Example Response
{ "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" }, { "id": "7a8c720d-32b7-47cc-a943-23e48d69e30a", "name": "a8d001aa-6946-4168-86d9-924c7d3ef8fb", "status": "DOWN", "admin_state_up": true, "fixed_ips": [ { "subnet_id": "a8d001aa-6946-4168-86d9-924c7d3ef8fb", "ip_address": "2a07:b980:4030:14::1" } ], "mac_address": "fa:16:3e:57:39:c3", "network_id": "26cf88ff-1a8c-4233-a8e6-183e1e299357", "tenant_id": "db82c9e1415a464ea68048baa8acc6b8", "project_id": "db82c9e1415a464ea68048baa8acc6b8", "device_id": "6c2fcea1-b785-4253-b84e-3d887e1c67e1", "device_owner": "network:router_interface_distributed", "security_groups": ["34acbeed-8f65-4875-86ca-66417b1733fd"], "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=7a8c720d-32b7-47cc-a943-23e48d69e30a" }, { "rel": "previous", "href": "https://{Endpoint}/v2.0/ports?limit=1&marker=7a8c720d-32b7-47cc-a943-23e48d69e30a&page_reverse=True" } ] }
{ "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" } ] }
{ "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" } ] }
{ "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" } ] }
{ "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" } ] }
{ "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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot