Liệt kê network port

GET/v2.0/ports

Liệt kê các network port mà project có thể truy cập.

Theo policy mặc định, chỉ các port thuộc project của user gửi request được trả về, trừ khi request được gửi bởi user có quyền admin.

Request

Tham số

admin_state_upboolean

Lọc kết quả theo trạng thái quản trị của tài nguyên: up (true) hoặc down (false).

binding:host_idstring

Lọc kết quả theo ID của host nơi port nằm.

device_idstring

Lọc kết quả theo ID của thiết bị sử dụng port này. Ví dụ: một server instance hoặc một logical router.

device_ownerstring

Lọc kết quả theo loại entity sử dụng port này. Ví dụ: compute:nova (server instance), network:dhcp (DHCP agent) hoặc network:router_interface (router interface).

idstring

Lọc kết quả theo ID của tài nguyên.

fixed_ipsarray

Lọc kết quả theo địa chỉ IP của port. Field này có một hoặc nhiều phần tử. Mỗi phần tử gồm địa chỉ IP (ip_address), một chuỗi con của địa chỉ IP (ip_address_substr) và/hoặc ID subnet mà địa chỉ IP được cấp từ đó (subnet_id).

ip_allocationstring

Lọc kết quả dựa trên việc port dùng cấp phát IP deferred, immediate hay không cấp phát (none).

mac_addressstring

Lọc kết quả theo địa chỉ MAC của port.

namestring

Lọc kết quả theo tên dễ đọc của tài nguyên.

network_idstring

Lọc kết quả theo ID của mạng gắn với port.

project_idstring

Lọc kết quả theo ID của project sở hữu tài nguyên.

revision_numberinteger

Lọc kết quả theo revision number của port.

statusstring

Lọc kết quả theo trạng thái port. Giá trị là ACTIVE, DOWN, BUILD hoặc ERROR.

tenant_idstring

Lọc kết quả theo ID của project sở hữu tài nguyên.

descriptionstring

Lọc kết quả theo mô tả dễ đọc của port.

mac_learning_enabledboolean

Lọc kết quả theo trạng thái mac_learning_enabled của tài nguyên: bật (true) hoặc tắt (false).

tagsstring

Danh sách tag để lọc kết quả. Các tài nguyên khớp tất cả tag trong danh sách sẽ được trả về. Các tag trong query phải phân tách bằng dấu phẩy.

tags-anystring

Danh sách tag để lọc kết quả. Các tài nguyên khớp bất kỳ tag nào trong danh sách sẽ được trả về. Các tag trong query phải phân tách bằng dấu phẩy.

not-tagsstring

Danh sách tag để lọc kết quả. Các tài nguyên khớp tất cả tag trong danh sách sẽ bị loại trừ. Các tag trong query phải phân tách bằng dấu phẩy.

not-tags-anystring

Danh sách tag để lọc kết quả. Các tài nguyên khớp bất kỳ tag nào trong danh sách sẽ bị loại trừ. Các tag trong query phải phân tách bằng dấu phẩy.

sort_dirstring

Hướng sắp xếp. Giá trị hợp lệ là asc (tăng dần) hoặc desc (giảm dần). Bạn có thể chỉ định nhiều cặp tham số query sort key và sort direction.

sort_keystring

Sắp xếp theo một thuộc tính của port. Bạn có thể chỉ định nhiều cặp tham số query sort key và sort direction. Các sort key được giới hạn ở: admin_state_up, device_id, device_owner, id, ip_allocation, mac_address, name, network_id, project_id, status, tenant_id.

fieldsstring

Các field bạn muốn server trả về. Nếu không chỉ định tham số query fields, API networking trả về tất cả thuộc tính được policy cho phép. Khi dùng tham số fields, API chỉ trả về tập thuộc tính được yêu cầu. Tham số fields có thể được chỉ định nhiều lần. Ví dụ, nếu bạn chỉ định fields=id&fields=name trong URL request, chỉ thuộc tính id và name được trả về.

Request mẫu

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:9696/v2.0/ports

Response

Tham số response

portsarraybắt buộc

Danh sách object port.

admin_state_upbooleanbắt buộc

Trạng thái quản trị của port: up (true) hoặc down (false).

allowed_address_pairsarraybắt buộc

Tập hợp không hoặc nhiều object allowed address pair, mỗi object chứa ip_address và mac_address. ip_address là bắt buộc, mac_address được lấy từ port nếu không chỉ định. Giá trị của ip_address có thể là địa chỉ IP hoặc CIDR. Server kết nối với port có thể gửi packet với địa chỉ nguồn khớp một trong các allowed address pair đã chỉ định.

binding:host_idstringbắt buộc

ID của host nơi port nằm.

binding:profileobjectbắt buộc

Dictionary cho phép ứng dụng chạy trên host cụ thể truyền và nhận thông tin vif port đặc thù của networking backend. API networking không định nghĩa định dạng cụ thể cho field này. Nếu request update là null, field response này sẽ là {}.

binding:vif_detailsobjectbắt buộc

Dictionary chứa thông tin bổ sung về port. Hiện tại các field sau được định nghĩa: port_filter và ovs_hybrid_plug. port_filter là boolean cho biết networking service có cung cấp các tính năng lọc port như security group và/hoặc chống giả mạo MAC/IP hay không. ovs_hybrid_plug là boolean thông báo cho API consumer (ví dụ nova) rằng nên dùng chiến lược hybrid plugging cho OVS.

binding:vif_typestringbắt buộc

Loại cơ chế được dùng cho port. API consumer như Nova có thể dùng giá trị này để xác định cách gắn thiết bị (ví dụ interface của VM) vào port. Các giá trị hiện có gồm ovs, bridge, macvtap, hw_veb, hostdev_physical, vhostuser, distributed và other. Ngoài ra có các giá trị đặc biệt: unbound và binding_failed. unbound nghĩa là port chưa được bind vào networking backend. binding_failed nghĩa là port bind vào networking backend thất bại.

binding:vnic_typestringbắt buộc

Loại vNIC mà port này nên gắn vào. Giá trị này dùng để xác định (các) mechanism driver dùng để bind port. Giá trị hợp lệ là normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic và remote-managed. Loại vNIC thực tế có sẵn phụ thuộc vào deployment.

created_atstringbắt buộc

Ngày giờ tạo tài nguyên. Định dạng timestamp ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. Ví dụ: 2015-08-27T09:49:58-05:00. Giá trị ±hh:mm, nếu có, là múi giờ so với UTC.

data_plane_statusstringbắt buộc

Trạng thái data plane bên dưới của port.

device_idstringbắt buộc

ID của thiết bị sử dụng port này. Ví dụ: một server instance hoặc một logical router.

device_ownerstringbắt buộc

Loại entity sử dụng port này. Ví dụ: compute:nova (server instance), network:dhcp (DHCP agent) hoặc network:router_interface (router interface).

dns_assignmentobjectbắt buộc

Dữ liệu được networking internal DNS gán cho port, gồm hostname, ip_address và fqdn.

dns_domainstringbắt buộc

Một DNS domain hợp lệ.

idstringbắt buộc

ID của port.

dns_namestringbắt buộc

Một DNS name hợp lệ.

extra_dhcp_optsarraybắt buộc

Tập hợp không hoặc nhiều cặp DHCP option bổ sung. Mỗi cặp gồm giá trị option và tên.

fixed_ipsarraybắt buộc

Các địa chỉ IP của port. Nếu port có nhiều địa chỉ IP, field này có nhiều phần tử. Mỗi phần tử gồm địa chỉ IP (ip_address) và ID subnet mà địa chỉ IP được cấp từ đó (subnet_id).

hintsobjectbắt buộc

Chỉ admin. Các giá trị sau điều khiển tính năng Userspace Tx packet steering của Open vSwitch: {"openvswitch": {"other_config": {"tx-steering": "hash|thread"}}}

ip_allocationstringbắt buộc

Cho biết port dùng cấp phát IP deferred, immediate hay không cấp phát (none).

mac_addressstringbắt buộc

Địa chỉ MAC của port. Nếu port dùng vnic_type direct-physical, giá trị field này bị ghi đè bằng địa chỉ MAC trong binding đang active, nếu có.

namestringbắt buộc

Tên dễ đọc của port.

network_idstringbắt buộc

ID của mạng gắn với port.

numa_affinity_policystring

Policy NUMA affinity của port được yêu cầu khi lập lịch máy ảo. Giá trị: none, required, preferred hoặc legacy.

port_security_enabledbooleanbắt buộc

Trạng thái port security. Giá trị hợp lệ là bật (true) và tắt (false). Nếu port security được bật cho port, các rule security group và anti-spoofing được áp dụng cho lưu lượng trên port. Nếu tắt, không áp dụng rule nào.

project_idstringbắt buộc

ID của project.

qos_network_policy_idstringbắt buộc

ID của QoS policy thuộc mạng nơi port này được gắn.

qos_policy_idstringbắt buộc

ID của QoS policy liên kết với port.

revision_numberintegerbắt buộc

Revision number của port.

resource_requestobject

Expose các tài nguyên Placement (ví dụ minimum-bandwidth) và trait (ví dụ vnic-type, physnet) được port yêu cầu cho Nova và Placement. Object resource_request chứa key request_groups và same_subtree.

security_groupsarraybắt buộc

ID các security group áp dụng cho port.

statusstringbắt buộc

Trạng thái port. Giá trị là ACTIVE, DOWN, BUILD hoặc ERROR.

tenant_idstringbắt buộc

ID của project.

updated_atstringbắt buộc

Ngày giờ cập nhật tài nguyên. Nếu tài nguyên chưa được cập nhật, field này là null. Định dạng timestamp ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm. Ví dụ: 2015-08-27T09:49:58-05:00.

propagate_uplink_statusbooleanbắt buộc

Trạng thái lan truyền uplink của port. Giá trị hợp lệ là bật (true) và tắt (false).

descriptionstringbắt buộc

Mô tả dễ đọc của port.

mac_learning_enabledboolean

Giá trị boolean cho biết MAC Learning có được bật trên port liên quan hay không.

port_trusted_vifbooleanbắt buộc

Trạng thái trusted VIF của port. Giá trị hợp lệ là true hoặc false. Giá trị field này nằm trong dict binding:profile của port.

tagsarraybắt buộc

Danh sách tag trên port.

Mã trạng thái

Thành công

Mã	Mô tả
200 - OK	Request thành công.

Lỗi

Mã	Mô tả
401 - Unauthorized	Cần xác thực trước khi gửi request.

Response mẫu

Response body

{
    "ports": [
        {
            "id": "525584a7-2106-483a-b313-5f9fc23dee7f",
            "name": "",
            "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "tenant_id": "",
            "mac_address": "fa:16:3e:b6:2e:7d",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "1c78faed-7262-403b-8f0a-097a77af8b65",
            "device_owner": "network:router_centralized_snat",
            "fixed_ips": [
                {
                    "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                    "ip_address": "192.168.1.61"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-30T09:20:01Z",
            "updated_at": "2025-10-01T20:24:29Z",
            "revision_number": 8,
            "project_id": ""
        },
        {
            "id": "726b31f7-4dde-4e93-a0cf-afeda1bfcaea",
            "name": "",
            "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "tenant_id": "f33507157a634f1cac71e06a70fb558e",
            "mac_address": "fa:16:3e:17:7c:d0",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "dhcpe52a9a47-9f6a-5406-9193-a4d7333f9889-f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "device_owner": "network:dhcp",
            "fixed_ips": [
                {
                    "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                    "ip_address": "192.168.1.2"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-30T09:19:36Z",
            "updated_at": "2025-10-01T20:24:36Z",
            "revision_number": 9,
            "project_id": "f33507157a634f1cac71e06a70fb558e"
        },
        {
            "id": "ef9338c5-8700-4ba4-8c10-d5ddd142a86e",
            "name": "",
            "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "tenant_id": "f33507157a634f1cac71e06a70fb558e",
            "mac_address": "fa:16:3e:8e:1e:d1",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "dhcp5eed51fb-728a-5fc4-90a4-1a768a8a68da-f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "device_owner": "network:dhcp",
            "fixed_ips": [
                {
                    "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                    "ip_address": "192.168.1.3"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-30T09:19:36Z",
            "updated_at": "2025-10-01T20:26:15Z",
            "revision_number": 15,
            "project_id": "f33507157a634f1cac71e06a70fb558e"
        },
        {
            "id": "f3247456-0e9a-4abb-bb37-2f0c002a9ada",
            "name": "",
            "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
            "tenant_id": "f33507157a634f1cac71e06a70fb558e",
            "mac_address": "fa:16:3e:60:56:4c",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "1c78faed-7262-403b-8f0a-097a77af8b65",
            "device_owner": "network:router_interface_distributed",
            "fixed_ips": [
                {
                    "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                    "ip_address": "192.168.1.1"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-30T09:20:01Z",
            "updated_at": "2025-09-30T09:20:12Z",
            "revision_number": 14,
            "project_id": "f33507157a634f1cac71e06a70fb558e"
        }
    ]
}