Help Center/ Elastic Cloud Server/ API Reference/ APIs/ NIC Management/ Querying the NICs That Can Be Attached to An ECS

Updated on 2025-12-10 GMT+08:00

View PDF

Querying the NICs That Can Be Attached to An ECS

Function

This API is used to query the NICs that can be attached to an ECS.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
If you are using identity policy-based authorization, the permissions listed below are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
ecs:cloudServers:showServer	read	instance *	g:ResourceTag/<tag-key> g:EnterpriseProjectId	ecs:cloudServers:get	-

URI

GET /v1/{project_id}/cloudservers/{server_id}/os-interface_extension

Table 1 describes the parameters in the URI.

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Specifies the project ID. For details about how to obtain the ID, see Obtaining a Project ID.
server_id	Yes	Specifies the ECS ID.

Request

None.

Response

Table 2 describes the response parameter.

**Table 2** Response parameters
Parameter	Type	Description
attachableQuantity	Object	Definition Specifies the number of NICs that can be attached to an ECS. For details, see Table 3. Range N/A
interfaceAttachments	Array of objects	Definition Specifies the NIC information list. For details, see Table 4. Range N/A

**Table 3** attachableQuantity field description
Parameter	Type	Description
free_efi_nic	Integer	Definition Specifies the remaining number of EFI NICs that can be attached to an ECS. Range N/A
free_scsi	Integer	Definition Specifies the number of SCSI disks that can be attached. Range N/A
free_blk	Integer	Definition Specifies the number of virtio_blk disks that can be attached. Range N/A
free_disk	Integer	Definition Specifies the total number of disks that can be attached. Range N/A
free_nic	Integer	Definition Specifies the total number of NICs that can be attached. Range N/A

**Table 4** **interfaceAttachments** field description
Parameter	Type	Description
port_state	String	Definition Specifies the NIC port status. Range N/A
fixed_ips	Array of objects	Definition Specifies the private IP address list for NICs. For details, see Table 5. Range N/A
net_id	String	Definition Specifies the network ID (network_id) that the NIC port belongs to. Range N/A
port_id	String	Definition Specifies the ID of the NIC port. Range N/A
mac_addr	String	Definition Specifies the MAC address of the NIC. Range N/A
delete_on_termination	Boolean	Definition Specifies whether to delete a NIC when detaching it. Range true: Delete the NIC. false: Do not delete the NIC.
driver_mode	String	Definition Specifies the NIC driver type, which is virtio by default. This parameter is a reserved field. Range N/A
min_rate	Integer	Definition Specifies the minimum NIC bandwidth. Range N/A
multiqueue_num	Integer	Definition Specifies the number of queues. Range 1~64
pci_address	String	Definition Specifies the BDF number of the elastic network interface in Linux GuestOS. NOTE: If the elastic network interface is not supported, no information will be returned. Range N/A
preserve_on_delete	Boolean	Definition Specifies whether to retain the NIC when it is deleted. Range true: Retain the NIC. false: Do not retain the NIC.

**Table 5** **fixed_ips** field description
Parameter	Type	Description
subnet_id	String	Definition Specifies the subnet of the NIC private IP address. Range N/A
ip_address	String	Definition Specifies the NIC private IP address. Range N/A

Example Request

Query the NICs that can be attached to an ECS.

GET https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/os-interface_extensione

Example Response

{
    "attachableQuantity": {
        "free_efi_nic": 0
    },
    "interfaceAttachments": [
        {
            "port_state": "ACTIVE",
            "fixed_ips": [
                {
                    "subnet_id": "ba31e1f5-fa76-4530-862c-5176fad033cf",
                    "ip_address": "192.168.0.33"
                }
            ],
            "net_id": "610a4af2-1d90-4d2b-8057-dc238b26febf",
            "port_id": "04819c0a-6a07-44b6-945e-fb932071888e",
            "mac_addr": "fa:16:3e:45:65:c4",
            "delete_on_termination": false,
			"preserve_on_delete": false,
            "driver_mode": null,
            "min_rate": null,
            "multiqueue_num": null,
            "pci_address": null
        }
    ]
}