Updated on 2024-04-18 GMT+08:00

Querying a Port

Function

This API is used to query a single port.

URI

GET /v1/{project_id}/ports/{port_id}

Table 1 describes the parameters.
Table 1 Parameter description

Name

Mandatory

Description

project_id

Yes

Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID.

port_id

Yes

Specifies the port ID that uniquely identifies the port.

Request Parameters

None

Example Request

GET https://{Endpoint}/v1/{project_id}/ports/d00f9c13-412f-4855-8af3-de5d8c24cd60

Response Parameters

Table 2 Response parameter

Name

Type

Description

port

port object

Specifies the port objects. For details, see Table 3.

Table 3 Description of the port field

Parameter

Type

Description

id

String

Specifies the port ID that uniquely identifies the port.

name

String

  • Specifies the port name.
  • The value can contain up to 255 characters. This parameter is left blank by default.

network_id

String

  • Specifies the ID of the network that the port belongs to.
  • The network ID must exist.

admin_state_up

Boolean

  • Specifies the administrative state of the port.
  • The default value is true.

mac_address

String

  • Specifies the port MAC address.
  • The MAC address is assigned by the system not specified by users.

fixed_ips

Array of fixed_ip objects

  • Specifies the port IP address. For example, the value is "fixed_ips": [{"subnet_id": "4dc70db6-cb7f-4200-9790-a6a910776bba", "ip_address": "192.169.25.79"}]. For details, see Table 4.
  • In IPv4 scenarios, a port supports only one fixed IP address that cannot be changed. In IPv6 scenarios, a port supports a maximum of two fixed IP addresses that cannot be changed.

device_id

String

  • Specifies the ID of the device that the port belongs to.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

device_owner

String

  • Specifies the owner of the device to which the port belongs, which can be a DHCP server, router, load balancer, or Nova.
  • The value can be network:dhcp, network:router_interface_distributed, compute:xxx, neutron:VIP_PORT, neutron:LOADBALANCERV2, neutron:LOADBALANCERV3, network:endpoint_interface, network:nat_gateway, or network:ucmp. (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 is not left blank, the port can only be deleted when this parameter value is neutron:VIP_PORT.

tenant_id

String

Specifies the project ID.

status

String

  • Specifies the port status. The status of a HANA SR-IOV VM port is always DOWN.
  • The value can be ACTIVE, BUILD, or DOWN.

security_groups

Array of strings

Specifies the security group UUID (extended attribute).

allowed_address_pairs

Array of allowed_address_pairs objects

  • Specifies the IP address and MAC address pair. An address pair consists of an IP address and a MAC address. For details, see Table 5.
  • The IP address cannot be 0.0.0.0/0.
  • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
  • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
  • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.

extra_dhcp_opts

Array of extra_dhcp_opt objects

Specifies the extended option (extended attribute) of DHCP. 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.

Note:

  • The internal_elb field is in boolean type and is available to common tenants. Set the value of this parameter to true only when you assign a virtual IP address to an internal network load balancer. Common tenants do not have the permission to change the value of this field, which is maintained by the system.

    Example:

    {"internal_elb": true}

  • The disable_security_groups field is in boolean type and is available to common tenants. The default value is false. In high-performance communication scenarios, you can set the parameter value to true, which makes this parameter to be available to common tenants. You can specify this parameter when creating a port. Currently, the value of this parameter can only be set to true.

    Example:

    {"disable_security_groups": true }

    Currently, the value can only be set to true. When the value is set to true, the FWaaS function does not take effect.

binding:vnic_type

String

  • Specifies the type of the bound vNIC.
  • The value can be normal or direct.
  • normal indicates software switching. direct indicates SR-IOV PCIe passthrough, which is not supported.

instance_id

String

  • Specifies the ID of the instance to which the port belongs, for example, RDS instance ID.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

instance_type

String

  • Specifies the type of the instance to which the port belongs, for example, RDS.
  • The system automatically sets this parameter, and you are not allowed to configure or change the parameter value.

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.

ipv6_bandwidth_id

String

  • Specifies the ID of the shared bandwidth associated with the IPv6 NIC.
  • This parameter is displayed only when the IPv6 NIC is associated with a shared bandwidth.
Table 4 fixed_ip object

Name

Type

Description

subnet_id

String

  • Specifies the subnet ID.

    If you use the management console, the value of this parameter is the IPv4 Subnet ID or IPv6 Subnet ID value.

  • You cannot change the parameter value.

ip_address

String

Specifies the port IP address.

Table 5 allowed_address_pairs objects

Name

Type

Description

ip_address

String

  • Specifies the IP address.
  • You cannot set it to 0.0.0.0/0.
  • Configure a dedicated security group for the port if the parameter allowed_address_pairs has a large CIDR block (subnet mask less than 24).
  • If the value of allowed_address_pairs is 1.1.1.1/0, the source/destination check is disabled.
  • Set allowed_address_pairs of the cloud server to 1.1.1.1/0.

mac_address

String

Specifies the MAC address.

Table 6 extra_dhcp_opt object

Name

Type

Description

opt_name

String

Specifies the name of the DHCP option. The value of this parameter can only be 51, indicating the DHCP lease time.

opt_value

String

Specifies the value of the DHCP option.

If the value of opt_name is 51, the value format of opt_value is Xh, indicating that the DHCP lease time is X hours.

The value of X is -1 or from 1 to 30000. If the value is -1, the DHCP lease time is infinite.

Table 7 binding:vif_details object

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.

Example Response

{
    "port": {
        "id": "d00f9c13-412f-4855-8af3-de5d8c24cd60",
        "name": "test",
        "status": "DOWN",
        "admin_state_up": "true",
        "fixed_ips": [
            {
                "subnet_id": "70f2e74b-e660-410a-b754-0ca46744348a",
                "ip_address": "10.128.1.10"
            }
        ],
        "mac_address": "fa:16:3e:d7:f2:6c",
        "network_id": "5b808927-13c9-4e60-a4f4-ed6ffe225167",
        "tenant_id": "43f2d1cca56a40729dcb17212482f34d",
        "device_id": "",
        "device_owner": "",
        "security_groups": [
            "02b4e8ee-74fa-4a31-802e-5490df11245e"
        ],
        "extra_dhcp_opts": [],
        "allowed_address_pairs": [],
        "binding:vnic_type": "normal",
        "instance_type": "RDS",
        "instance_id": "03a4e9ee-64eb-4a31-802e-5490df22146c"
    }
}

Status Code

See Status Codes.

Error Code

See Error Codes.