Chuyển tới nội dung chính

Cập nhật network port

PUT/v2.0/ports/{port_id}

Cập nhật thuộc tính của một network port hiện có.

Chỉ các field có thể thay đổi mới được cập nhật. Các field như id, network_id, project_id / tenant_id và timestamp là chỉ đọc.

Request​

Tham số path​

port_idstringbắt buộc

ID của port cần cập nhật.

Cấu trúc body​

Object JSON cấp cao nhất phải chứa một object port duy nhất với một hoặc nhiều thuộc tính có thể cập nhật.

Tham số có thể cập nhật​

portobjectbắt buộc

Object bao ngoài chứa các field cần cập nhật. Chỉ cung cấp các field bạn muốn thay đổi.

namestring

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

descriptionstring

Mô tả dễ đọc (mặc định là chuỗi rỗng).

admin_state_upboolean

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

device_idstring

ID của thiết bị (server, router, v.v.) sử dụng port này.

device_ownerstring

Loại entity sử dụng port (compute:nova, network:dhcp, network:router_interface, v.v.).

security_groupsarray

Danh sách ID security group cần áp dụng. Thay thế danh sách hiện có.

fixed_ipsarray

Danh sách ánh xạ fixed IP mới. Mỗi phần tử có thể gồm subnet_id và/hoặc ip_address. Toàn bộ danh sách bị thay thế nếu bạn cung cấp. Xem tài liệu tạo port để biết cách cấp phát.

allowed_address_pairsarray

Danh sách object, mỗi object có ip_address (bắt buộc) và mac_address tuỳ chọn. Thay thế danh sách hiện có.

extra_dhcp_optsarray

Danh sách object DHCP option (opt_name, opt_value). Thay thế danh sách hiện có.

port_security_enabledboolean

Bật/tắt việc áp dụng security group và anti-spoofing.

qos_policy_idstring

QoS policy cần liên kết (hoặc null để xoá).

binding:host_idstring

ID host nơi port nằm. Thường do hệ thống / scheduler đặt; chỉ admin được ghi đè.

binding:profileobject

Dict thông tin VIF đặc thù backend. Dùng null để đặt lại thành {}. Có thể chứa device_mac_address cho binding direct-physical để ghi đè mac_address được expose.

binding:vnic_typestring

Loại vNIC mong muốn (normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, remote-managed). Việc thay đổi sau khi bind lần đầu có thể bị deployment giới hạn.

mac_addressstring

Địa chỉ MAC của port. Thường không thể thay đổi sau khi tạo, trừ một số trường hợp binding cụ thể (ví dụ direct-physical với device_mac_address).

dns_domainstring

DNS domain cần liên kết.

dns_namestring

DNS name (hostname) cần liên kết.

hintsobject

Hint mechanism driver chỉ admin (ví dụ {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Độ dài tối đa 4095 ký tự sau khi serialize.

numa_affinity_policystring

Policy NUMA affinity: none, required, preferred hoặc legacy.

propagate_uplink_statusboolean

Có bật lan truyền trạng thái uplink hay không.

mac_learning_enabledboolean

Bật MAC learning trên port.

port_trusted_vifboolean

Trạng thái trusted VIF. Được phản ánh trong binding:profile.

allowed_address_pairs[*].ip_addressstringbắt buộc

Địa chỉ IP hoặc CIDR.

allowed_address_pairs[*].mac_addressstring

Địa chỉ MAC; mặc định dùng MAC của port nếu bỏ qua.

Lưu ý: Các field bị bỏ qua sẽ giữ nguyên. Với thuộc tính dạng list (ví dụ security_groups, allowed_address_pairs, fixed_ips), cung cấp list sẽ thay thế toàn bộ list hiện có.

Request mẫu​

curl -ks -X PUT -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: gAAAAA<...>' \
     -d '{
  "port": {
    "name": "dhcp-port",
    "device_owner": "network:dhcp",
    "device_id": "dhcpe52a9a47-9f6a-5406-9193-a4d7333f9889-f858b8d1-e66b-4a48-bc2e-3f16483b1b58"
  }
}' \
https://<node_IP_addr>:9696/v2.0/ports/c85ae844-9ff5-4866-97da-546c3bf0144b

Response​

Tham số response​

Nếu thành công, API trả về một object port đã cập nhật với tất cả thuộc tính hiện tại.

portobjectbắt buộc

Object bao ngoài của port.

idstringbắt buộc

ID của port.

namestringbắt buộc

Tên port.

network_idstringbắt buộc

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

tenant_idstringbắt buộc

ID project (field legacy).

project_idstringbắt buộc

ID project sở hữu.

mac_addressstringbắt buộc

Địa chỉ MAC (có thể bị ghi đè với direct-physical).

admin_state_upbooleanbắt buộc

Trạng thái quản trị.

statusstringbắt buộc

Trạng thái port: ACTIVE, DOWN, BUILD hoặc ERROR.

device_idstringbắt buộc

ID của thiết bị được gắn.

device_ownerstringbắt buộc

Loại entity sử dụng port.

fixed_ipsarraybắt buộc

Danh sách {subnet_id, ip_address} của port.

allowed_address_pairsarraybắt buộc

Allowed address pair.

extra_dhcp_optsarraybắt buộc

Các object DHCP option bổ sung.

security_groupsarraybắt buộc

ID các security group.

descriptionstringbắt buộc

Mô tả.

binding:vnic_typestringbắt buộc

Loại vNIC.

binding:profileobjectbắt buộc

Thông tin VIF đặc thù backend ({} nếu không có).

binding:host_idstringbắt buộc

ID host nơi port nằm.

binding:vif_typestringbắt buộc

Loại mechanism driver hoặc unbound / binding_failed.

binding:vif_detailsobjectbắt buộc

Thông tin bổ sung (port_filter, ovs_hybrid_plug, v.v.).

port_security_enabledbooleanbắt buộc

Port security có được bật hay không.

qos_policy_idstringbắt buộc

QoS policy áp dụng trực tiếp (hoặc null).

qos_network_policy_idstringbắt buộc

QoS policy của mạng (hoặc null).

resource_requestobject

Các nhóm tài nguyên / trait Placement được yêu cầu.

tagsarraybắt buộc

Danh sách tag.

created_atstringbắt buộc

Thời điểm tạo (ISO 8601).

updated_atstringbắt buộc

Thời điểm cập nhật gần nhất (ISO 8601) hoặc null.

revision_numberintegerbắt buộc

Revision number.

ip_allocationstringbắt buộc

Chế độ cấp phát (immediate, deferred hoặc none).

dns_assignmentobjectbắt buộc

Gán DNS nội bộ (hostname, ip_address, fqdn).

dns_domainstringbắt buộc

DNS domain.

dns_namestringbắt buộc

DNS name.

hintsobjectbắt buộc

Hint điều khiển OVS Userspace Tx packet steering (chỉ admin) nếu có.

numa_affinity_policystring

Policy NUMA affinity.

propagate_uplink_statusbooleanbắt buộc

Cờ lan truyền trạng thái uplink.

mac_learning_enabledboolean

MAC learning có được bật hay không.

port_trusted_vifbooleanbắt buộc

Trạng thái trusted VIF.

data_plane_statusstringbắt buộc

Trạng thái data plane bên dưới nếu được báo cáo.

Mã trạng thái​

Thành công​

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

Lỗi​

MãMô tả
400 - Bad RequestNội dung request không hợp lệ.
401 - UnauthorizedCần xác thực trước khi gửi request.
403 - ForbiddenPolicy không cho phép user hiện tại thực hiện thao tác này.
404 - Not FoundKhông tìm thấy tài nguyên được yêu cầu.
409 - ConflictThao tác xung đột với một thao tác khác trên tài nguyên.
412 - Precondition FailedServer không đáp ứng điều kiện tiên quyết của request.

Response mẫu​

Response body
{
    "port": {
        "id": "2d74fa0c-3e43-4fd9-a234-cbb4996cc684",
        "name": "dhcp-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "tenant_id": "f33507157a634f1cac71e06a70fb558e",
        "mac_address": "fa:16:3e:7f:ae:b2",
        "admin_state_up": true,
        "status": "DOWN",
        "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.12"
            }
        ],
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "security_groups": [
            "e1c1aa83-7302-4493-9cf4-43c2407e8074"
        ],
        "description": "",
        "binding:vnic_type": "normal",
        "port_security_enabled": true,
        "qos_policy_id": null,
        "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
        "tags": [],
        "created_at": "2025-10-08T08:05:12Z",
        "updated_at": "2025-10-08T08:21:32Z",
        "revision_number": 3,
        "project_id": "f33507157a634f1cac71e06a70fb558e"
    }
}

Xem thêm​