All Products
Search
Document Center

:DescribeNetworkInterfaces

最終更新日:Jan 15, 2024

Queries the details of elastic network interfaces (ENIs).

Usage notes

You can call the DescribeNetworkInterfaces operation for paged query by specifying the MaxResults or NextToken parameter. During a paged query, when you call the DescribeNetworkInterfaces operation to retrieve the first page of results, set MaxResults to specify the maximum number of entries to return in the call. The return value of NextToken is a pagination token that can be used in the next call to retrieve a new page of results. When you call the DescribeNetworkInterfaces operation to retrieve a new page of results, set NextToken to the NextToken value returned in the previous call and set MaxResults to specify the maximum number of entries to return in this call.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action String Yes DescribeNetworkInterfaces

The operation that you want to perform. Set the value to DescribeNetworkInterfaces.

RegionId String Yes cn-hangzhou

The region ID of the ENI. You can call the DescribeRegions operation to query the most recent region list.

Tag.N.Key String No TestKey

The key of tag N of the ENI. Valid values of N: 1 to 20.

Tag.N.Value String No TestValue

The value of tag N of the ENI. Valid values of N: 1 to 20.

If a single tag is specified to query resources, up to 1,000 resources that have the tag can be displayed in the response. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags can be displayed in the response. To query more than 1,000 ENIs that have specified tags added, call the ListTagResources operation.

ResourceGroupId String No rg-bp67acfmxazb4p****

The ID of the resource group. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group are returned.

Note ENIs in the default resource group are displayed in the response regardless of how this parameter is set.
VSwitchId String No vsw-bp16usj2p27htro3****

The ID of the vSwitch to which the ENI is connected.

VpcId String No vpc-bp1j7w3gc1cexjqd****

The ID of the virtual private cloud (VPC) to which the ENI belongs.

PrimaryIpAddress String No 192.168.**.**

The primary private IPv4 address of the ENI.

SecurityGroupId String No sg-bp144yr32sx6ndw****

The ID of the security group to which the secondary ENI belongs.

  • To query the details of secondary ENIs based on the ID of a security group, specify this parameter.
  • To query the details of primary ENIs based on the ID of a security group, call the DescribeInstances operation with the SecurityGroupId parameter specified.
NetworkInterfaceName String No test-eni-name

The name of the ENI.

Type String No Secondary

The type of the ENI. Valid values:

  • Primary
  • Secondary

This parameter is empty by default, which indicates that both primary and secondary ENIs are queried.

InstanceId String No i-bp1e2l6djkndyuli****

The ID of the instance to which the ENI is attached.

ServiceManaged Boolean No true

Specifies whether the user of the ENI is an Alibaba Cloud service or a distributor.

Status String No Available

The status of the ENI. Valid values:

  • Available: The ENI is available.
  • Attaching: The ENI is being attached to an instance.
  • InUse: The ENI is attached to an instance.
  • Detaching: The ENI is being detached from an instance.
  • Deleting: The ENI is being deleted.

This parameter is empty by default, which indicates that ENIs in all states are queried.

PageNumber Integer No 1
Note This parameter is no longer used. We recommend that you specify the MaxResults or NextToken parameter for a paged query.
PageSize Integer No 100
Note This parameter is no longer used. We recommend that you specify the MaxResults or NextToken parameter for a paged query.
NextToken String No AAAAAdDWBF2****

The pagination token that is used in the next request to retrieve a new page of results. You do not need to specify this parameter for the first request. You must specify the token that is obtained from the previous query as the value of NextToken.

For information about how to check the responses returned by this operation, see the "Usage notes" section in this topic.

MaxResults Integer No 50

The maximum number of entries per page. Valid values: 10 to 500.

Default value:

  • If this parameter is not specified or if this parameter is set to a value less than 10, the default value is 10.
  • If this parameter is set to a value greater than 500, the default value 500 is used.
PrivateIpAddress.N String No 192.168.**.**

Secondary private IPv4 address N of the ENI. Valid values of N: 1 to 100.

NetworkInterfaceId.N String No eni-bp125p95hhdhn3ot****

The ID of ENI N. Valid values of N: 1 to 100.

Ipv6Address.N String No 2408:4321:180:1701:94c7:bc38:3bfa:****

IPv6 address N of the ENI. Valid values of N: 1 to 100.

Response parameters

Parameter

Type

Example

Description

NextToken String AAAAAdDWBF2****

A pagination token. It can be used in the next request to retrieve a new page of results.

PageSize Integer 1

The number of entries per page.

Note This parameter will be removed in the future. We recommend that you use the NextToken and MaxResults parameters for a paged query.
PageNumber Integer 1

The page number.

Note This parameter will be removed in the future. We recommend that you use the NextToken and MaxResults parameters for a paged query.
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

TotalCount Integer 2

The total number of ENIs returned.

Note If you specify the MaxResults and NextToken parameters to perform a paged query, the value of the TotalCount response parameter is invalid.
NetworkInterfaceSets Array of NetworkInterfaceSet

Details of the ENIs.

NetworkInterfaceSet
CreationTime String 2019-12-25T12:31:31Z

The time when the ENI was created.

VpcId String vpc-bp1j7w3gc1cexjqd****

The ID of the VPC to which the ENI belongs.

Type String Secondary

The type of the ENI.

Status String Available

The status of the ENI.

NetworkInterfaceTrafficMode String Standard

The communication mode of the ENI. Valid values:

  • Standard: uses the TCP communication mode.
  • HighPerformance: uses the remote direct memory access (RDMA) communication mode with Elastic RDMA Interface (ERI) enabled.

    Note The parameter can have a value of HighPerformance only when the ENI is attached to a c7re RDMA-enhanced instance that resides in Beijing Zone K.

NetworkInterfaceName String my-eni-name

The name of the ENI.

MacAddress String 00:16:3e:12:**:**

The media access control (MAC) address of the ENI.

QueuePairNumber Integer 0
Note This parameter is in invitational preview and is not publicly available.
NetworkInterfaceId String eni-bp125p95hhdhn3ot****

The ID of the ENI.

ServiceID Long 12345678910

The ID of the distributor to which the ENI belongs.

InstanceId String i-bp1e2l6djkndyuli****

The ID of the instance to which the ENI is bound.

Note If the ENI is managed and controlled by other Alibaba Cloud services, no instance ID is returned.
OwnerId String 123456****

The ID of the account to which the ENI belongs.

ServiceManaged Boolean true

Indicates whether the user of the ENI is an Alibaba Cloud service or a distributor.

VSwitchId String vsw-bp16usj2p27htro3****

The ID of the vSwitch with which the ENI is associated.

Description String DescriptionTest

The description of the ENI.

ResourceGroupId String rg-2ze88m67qx5z****

The ID of the resource group to which the ENI belongs.

ZoneId String cn-hangzhou-e

The zone ID of the ENI.

PrivateIpAddress String 172.17.**.**

The private IP address of the ENI.

QueueNumber Integer 8

The number of queues supported by the ENI.

  • If the ENI is a secondary ENI in the InUse (InUse) state and the number of queues supported by the ENI has never been modified, the default number of queues per secondary ENI that the instance type supports is returned.
  • If the number of queues supported by the secondary ENI has been modified, the new number of queues is returned.
  • If the ENI is a secondary ENI in the Available (Available) state and the number of queues supported by the ENI has never been modified, an empty value is returned.
  • If the ENI is a primary ENI, the default number of queues per primary ENI that the instance type supports is returned.
PrivateIpSets Array of PrivateIpSet

The private IP addresses of the ENI.

PrivateIpSet
PrivateIpAddress String 172.17.**.**

The private IP address of the ENI.

Primary Boolean true

Indicates whether the IP address is the primary private IP address. Valid values:

  • true: The IP address is the primary private IP address.
  • false: The IP address is a secondary private IP address.
AssociatedPublicIp Object

Details about the elastic IP address (EIP) associated with the ENI.

PublicIpAddress String 116.62.**.**

The EIP of the ENI.

AllocationId String null
Note This parameter is in invitational preview and is not publicly available.
Ipv6Sets Array of Ipv6Set

The IPv6 addresses assigned to the ENI.

Ipv6Set
Ipv6Address String 2408:4321:180:1701:94c7:bc38:3bfa:****

The IPv6 address assigned to the ENI.

Ipv4PrefixSets Array of Ipv4PrefixSet

The IPv4 prefixes assigned to the ENI.

Ipv4PrefixSet
Ipv4Prefix String 192.168.**.0/28

The IPv4 prefix assigned to the ENI.

Ipv6PrefixSets Array of Ipv6PrefixSet

The IPv6 prefixes assigned to the ENI.

Ipv6PrefixSet
Ipv6Prefix String 2001:db8:1234:1a00:****::/80

The IPv6 prefixes assigned to the ENI.

Tags Array of Tag

The tags of the ENI.

Tag
TagValue String TestValue

The tag value of the ENI.

TagKey String TestKey

The tag key of the ENI.

SecurityGroupIds Array of String sg-bp18kz60mefsicfg****

The IDs of the security groups to which the ENI belongs.

AssociatedPublicIp Object

The EIP associated with the secondary private IP address of the ENI.

PublicIpAddress String 116.62.**.**

The EIP of the ENI.

AllocationId String null
Note This parameter is in invitational preview and is not publicly available.
Attachment Object
Note This parameter is in invitational preview and is not publicly available.
DeviceIndex Integer 0
Note This parameter is in invitational preview and is not publicly available.
InstanceId String null
Note This parameter is in invitational preview and is not publicly available.
TrunkNetworkInterfaceId String null
Note This parameter is in invitational preview and is not publicly available.
NetworkCardIndex Integer 0

The index of the network card.

  • If the ENI is in the Available (Available) state or if no network card index was specified when the ENI was attached, this parameter has no value.
  • If the ENI is in the InUse (InUse) state and a network card index was specified when the ENI was attached, the specified network card index is returned as the value of this parameter.
DeleteOnRelease Boolean true

Indicates whether to release the ENI when the associated instance is released. Valid values:

  • true
  • false

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeNetworkInterfaces
&RegionId=cn-hangzhou
&PrivateIpAddress.1=192.168.**.**
&PrivateIpAddress.2=192.168.**.**
&NextToken=AAAAAdDWBF2****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeNetworkInterfacesResponse>
    <NextToken>AAAAAdDWBF2****</NextToken>
    <PageSize>1</PageSize>
    <PageNumber>1</PageNumber>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <TotalCount>2</TotalCount>
    <NetworkInterfaceSets>
        <CreationTime>2019-12-25T12:31:31Z</CreationTime>
        <VpcId>vpc-bp1j7w3gc1cexjqd****</VpcId>
        <Type>Secondary</Type>
        <Status>Available</Status>
        <NetworkInterfaceTrafficMode>Standard</NetworkInterfaceTrafficMode>
        <NetworkInterfaceName>my-eni-name</NetworkInterfaceName>
        <MacAddress>00:16:3e:12:**:**</MacAddress>
        <QueuePairNumber>0</QueuePairNumber>
        <NetworkInterfaceId>eni-bp125p95hhdhn3ot****</NetworkInterfaceId>
        <ServiceID>12345678910</ServiceID>
        <InstanceId>i-bp1e2l6djkndyuli****</InstanceId>
        <OwnerId>123456****</OwnerId>
        <ServiceManaged>true</ServiceManaged>
        <VSwitchId>vsw-bp16usj2p27htro3****</VSwitchId>
        <Description>DescriptionTest</Description>
        <ResourceGroupId>rg-2ze88m67qx5z****</ResourceGroupId>
        <ZoneId>cn-hangzhou-e</ZoneId>
        <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
        <QueueNumber>8</QueueNumber>
        <PrivateIpSets>
            <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
            <Primary>true</Primary>
            <AssociatedPublicIp>
                <PublicIpAddress>116.62.**.**</PublicIpAddress>
                <AllocationId>null</AllocationId>
            </AssociatedPublicIp>
        </PrivateIpSets>
        <Ipv6Sets>
            <Ipv6Address>2408:4321:180:1701:94c7:bc38:3bfa:****</Ipv6Address>
        </Ipv6Sets>
        <Ipv4PrefixSets>
            <Ipv4Prefix>192.168.**.0/28</Ipv4Prefix>
        </Ipv4PrefixSets>
        <Ipv6PrefixSets>
            <Ipv6Prefix>2001:db8:1234:1a00:****::/80</Ipv6Prefix>
        </Ipv6PrefixSets>
        <Tags>
            <TagValue>TestValue</TagValue>
            <TagKey>TestKey</TagKey>
        </Tags>
        <SecurityGroupIds>sg-bp18kz60mefsicfg****</SecurityGroupIds>
        <AssociatedPublicIp>
            <PublicIpAddress>116.62.**.**</PublicIpAddress>
            <AllocationId>null</AllocationId>
        </AssociatedPublicIp>
        <Attachment>
            <DeviceIndex>0</DeviceIndex>
            <InstanceId>null</InstanceId>
            <TrunkNetworkInterfaceId>null</TrunkNetworkInterfaceId>
            <NetworkCardIndex>0</NetworkCardIndex>
            <DeleteOnRelease>true</DeleteOnRelease>
        </Attachment>
    </NetworkInterfaceSets>
</DescribeNetworkInterfacesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "NextToken" : "AAAAAdDWBF2****",
  "PageSize" : 1,
  "PageNumber" : 1,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount" : 2,
  "NetworkInterfaceSets" : [ {
    "CreationTime" : "2019-12-25T12:31:31Z",
    "VpcId" : "vpc-bp1j7w3gc1cexjqd****",
    "Type" : "Secondary",
    "Status" : "Available",
    "NetworkInterfaceTrafficMode" : "Standard",
    "NetworkInterfaceName" : "my-eni-name",
    "MacAddress" : "00:16:3e:12:**:**",
    "QueuePairNumber" : 0,
    "NetworkInterfaceId" : "eni-bp125p95hhdhn3ot****",
    "ServiceID" : 12345678910,
    "InstanceId" : "i-bp1e2l6djkndyuli****",
    "OwnerId" : "123456****",
    "ServiceManaged" : true,
    "VSwitchId" : "vsw-bp16usj2p27htro3****",
    "Description" : "DescriptionTest",
    "ResourceGroupId" : "rg-2ze88m67qx5z****",
    "ZoneId" : "cn-hangzhou-e",
    "PrivateIpAddress" : "172.17.**.**",
    "QueueNumber" : 8,
    "PrivateIpSets" : [ {
      "PrivateIpAddress" : "172.17.**.**",
      "Primary" : true,
      "AssociatedPublicIp" : {
        "PublicIpAddress" : "116.62.**.**",
        "AllocationId" : "null"
      }
    } ],
    "Ipv6Sets" : [ {
      "Ipv6Address" : "2408:4321:180:1701:94c7:bc38:3bfa:****"
    } ],
    "Ipv4PrefixSets" : [ {
      "Ipv4Prefix" : "192.168.**.0/28"
    } ],
    "Ipv6PrefixSets" : [ {
      "Ipv6Prefix" : "2001:db8:1234:1a00:****::/80"
    } ],
    "Tags" : [ {
      "TagValue" : "TestValue",
      "TagKey" : "TestKey"
    } ],
    "SecurityGroupIds" : [ "sg-bp18kz60mefsicfg****" ],
    "AssociatedPublicIp" : {
      "PublicIpAddress" : "116.62.**.**",
      "AllocationId" : "null"
    },
    "Attachment" : {
      "DeviceIndex" : 0,
      "InstanceId" : "null",
      "TrunkNetworkInterfaceId" : "null",
      "NetworkCardIndex" : 0,
      "DeleteOnRelease" : "true"
    }
  } ]
}

Error codes

HTTP status code

Error code

Error message

Description

400 MissingParameter %s A required parameter is not specified.
400 UnsupportedParameter %s A specified parameter is not supported.
400 InvalidParameter %s Invalid parameter value.
400 InvalidInstanceID.Malformed %s Invalid InstanceId format.
400 InvalidOperation.InvalidEcsState %s This operation cannot be performed on the instance in the current state.
400 InvalidOperation.InvalidEniState %s This operation cannot be performed on the ENI in the current state.
400 InvalidOperation.DetachPrimaryEniNotAllowed %s The primary ENI cannot be detached from the instance.
400 Forbidden.RegionId %s The service is unavailable in the region for the moment.
400 InvalidRegionId.MalFormed The specified parameter RegionId is not valid. Invalid RegionId value.
403 InvalidUserType.NotSupported %s Your account does not support this operation.
403 Abs.InvalidAccount.NotFound %s Your Alibaba Cloud account is not found, or your AccessKey pair has expired.
403 Forbidden.NotSupportRAM %s Resource Access Management (RAM) users do not have the permissions to perform this operation.
403 Forbidden.SubUser %s You have no access to the resource. Contact the owner of the Alibaba Cloud account.
403 MaxEniCountExceeded %s The maximum number of ENIs that can be managed is exceeded.
403 EniPerInstanceLimitExceeded %s The maximum number of ENIs that can be attached to the instance is exceeded.
403 InvalidOperation.AvailabilityZoneMismatch %s The operation is invalid.
403 InvalidOperation.VpcMismatch %s The operation is invalid. Check whether the VPC in the operation corresponds to other parameters.
403 SecurityGroupInstanceLimitExceed %s The maximum number of instances in the security group is exceeded.
403 InvalidSecurityGroupId.NotVpc %s Invalid security group ID. The network type of the specified security group is not VPC.
403 InvalidOperation.InvalidEniType %s This operation cannot be performed on this type of ENI.
403 InvalidVpc.Empty %s No vSwitches exist in the specified VPC. For more information, see the return value of the %s placeholder in the error message.
404 InvalidEcsId.NotFound %s The instance ID is not found.
404 InvalidEniId.NotFound %s The ENI ID is not found.
404 InvalidVSwitchId.NotFound %s The specified vSwitch ID is not found.
404 InvalidSecurityGroupId.NotFound %s The specified security group ID is not found.

For a list of error codes, see Service error codes.