全部产品
Search
文档中心

云服务器 ECS:DescribeNetworkInterfaces - 查看弹性网卡(ENI)列表

更新时间:Nov 29, 2024

调用DescribeNetworkInterfaces接口,并可以指定ResourceGroupId、VSwitchId、InstanceId等参数,查询一个或多个弹性网卡(ENI)的详细信息。

接口说明

DescribeNetworkInterfaces接口支持指定MaxResultsNextToken参数通过分页查询。具体使用说明:

  • 分页查询首页时,仅需设置MaxResults以限制返回信息的条目数,返回结果中的NextToken将作为查询后续页的凭证。

  • 查询后续页时,将NextToken参数设置为上一次返回结果中获取到的NextToken作为查询凭证,并设置MaxResults限制返回条目数。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:DescribeNetworkInterfacesget
*NetworkInterface
acs:ecs:{#regionId}:{#accountId}:eni/{#eniId}

请求参数

名称类型必填描述示例值
RegionIdstring

所在地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou
Tagarray<object>

标签列表

object
Keystring

弹性网卡的标签键。N 的取值范围:1~20

TestKey
Valuestring

弹性网卡的标签值。N 的取值范围:1~20

使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个;使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,请使用 ListTagResources 接口进行查询。

TestValue
ResourceGroupIdstring

资源组 ID。使用该参数过滤资源时,资源数量不能超过 1000 个。

说明 不支持默认资源组过滤。
rg-bp67acfmxazb4p****
VSwitchIdstring

弹性网卡所属的交换机 ID。

vsw-bp16usj2p27htro3****
VpcIdstring

弹性网卡所属的专有网络 VPC ID。

vpc-bp1j7w3gc1cexjqd****
PrimaryIpAddressstring

弹性网卡主私网 IPv4 地址。

192.168.**.**
SecurityGroupIdstring

辅助网卡对应的安全组 ID。

  • 如果您需要通过安全组 ID 查询辅助网卡的信息,请指定该参数。
  • 如果您需要通过安全组 ID 查询主网卡信息,请调用 DescribeInstances 指定SecurityGroupId参数进行查询。
sg-bp144yr32sx6ndw****
NetworkInterfaceNamestring

弹性网卡的名称。长度为 2~128 个字符,支持 Unicode 中 letter 分类下的字符(其中包括英文、中文和数字等)。可以包含半角冒号(:)、下划线(_)、半角句号(.)或者短划线(-)。

test-eni-name
Typestring

弹性网卡类型。取值范围:

  • Primary:主网卡。
  • Secondary:辅助网卡。

默认值:空,表示查询所有类型。

Secondary
InstanceIdstring

弹性网卡当前附加的实例 ID。

i-bp1e2l6djkndyuli****
ServiceManagedboolean

该弹性网卡的使用者是否为云产品或虚商。

true
Statusstring

弹性网卡的状态。取值范围:

  • Available:可用。
  • Attaching:附加中。
  • InUse:已附加。
  • Detaching:分离中。
  • Deleting:删除中。

默认值:空,表示查询所有状态。

Available
PageNumberdeprecatedinteger
说明 该参数已废弃,建议您通过指定 MaxResults 或 NextToken 参数时使用分页方式查询。
1
PageSizedeprecatedinteger
说明 该参数已废弃,建议您通过指定 MaxResults 或 NextToken 参数时使用分页方式查询。
100
NextTokenstring

查询凭证(Token),取值为上一次 API 调用返回的NextToken参数值。

有关本接口查看返回数据的设置方式,请参见上文接口说明。

AAAAAdDWBF2****
MaxResultsinteger

分页查询时每页的最大条目数。取值范围:10~500。

默认值:

  • 当不设置值或设置的值小于 10 时,默认值为 10。
  • 当设置的值大于 500 时,默认值为 500。
50
PrivateIpAddressarray

弹性网卡的辅助私网 IPv4 地址。N 的取值范围:1~100。

string

弹性网卡的辅助私网 IPv4 地址。N 的取值范围:1~100。

192.168.**.**
NetworkInterfaceIdarray

弹性网卡 ID。N 的取值范围:1~100。

string

弹性网卡 ID。N 的取值范围:1~100。

eni-bp125p95hhdhn3ot****
Ipv6Addressarray

弹性网卡的 IPv6 地址。N 表示可以设置多个 IPv6 地址,N 的取值范围:1~100。

string

弹性网卡的 IPv6 地址。N 表示可以设置多个 IPv6 地址,N 的取值范围:1~100。

2408:4321:180:1701:94c7:bc38:3bfa:****

返回参数

名称类型描述示例值
object
NextTokenstring

本次调用返回的查询凭证值。

AAAAAdDWBF2****
PageSizeinteger

分页查询参数。

说明 该参数即将下线,推荐您使用 NextToken 与 MaxResults 完成分页查询操作。
1
PageNumberinteger

分页查询参数。

说明 该参数即将下线,推荐您使用 NextToken 与 MaxResults 完成分页查询操作。
1
RequestIdstring

请求 ID。

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCountinteger

返回的弹性网卡总数。

说明 使用MaxResultsNextToken参数进行分页查询时,返回的TotalCount参数值无意义。
2
NetworkInterfaceSetsarray<object>

弹性网卡信息组成的集合。

NetworkInterfaceSetobject
CreationTimestring

创建时间。

2019-12-25T12:31:31Z
VpcIdstring

弹性网卡所属的专有网络 VPC ID。

vpc-bp1j7w3gc1cexjqd****
Typestring

弹性网卡的类型。取值范围:

  • Primary:主网卡。
  • Secondary:辅助网卡。
Secondary
Statusstring

弹性网卡的状态。取值范围:

  • Available:可用。
  • Attaching:附加中。
  • InUse:已附加。
  • Detaching:分离中。
  • Deleting:删除中。
Available
NetworkInterfaceTrafficModestring

弹性网卡的通讯模式。可能值:

  • Standard:使用 TCP 通讯模式。
  • HighPerformance:开启 ERI(Elastic RDMA Interface)接口,使用 RDMA 通讯模式。
说明 HighPerformance 参数值只支持 RDMA 增强型实例规格族 c7re,目前仅支持在华北 2(北京)的可用区 K 设置该参数值。
Standard
NetworkInterfaceNamestring

弹性网卡的名称。

my-eni-name
MacAddressstring

弹性网卡的 MAC 地址。

00:16:3e:12:**:**
QueuePairNumberinteger
说明 该参数正在邀测中,暂未开放使用。
0
NetworkInterfaceIdstring

弹性网卡 ID。

eni-bp125p95hhdhn3ot****
ServiceIDlong

弹性网卡对应的虚商 ID。

12345678910
InstanceIdstring

弹性网卡附加的实例 ID。

说明 由其他阿里云服务管理和控制的弹性网卡不会返回实例 ID。
i-bp1e2l6djkndyuli****
OwnerIdstring

弹性网卡的所属账号 ID。

123456****
ServiceManagedboolean

该弹性网卡的使用者是否为云产品或虚商。

true
VSwitchIdstring

VPC 的交换机 ID。

vsw-bp16usj2p27htro3****
Descriptionstring

描述。

DescriptionTest
ResourceGroupIdstring

资源组 ID。

rg-2ze88m67qx5z****
ZoneIdstring

可用区 ID。

cn-hangzhou-e
PrivateIpAddressstring

弹性网卡的私网 IP 地址。

172.17.**.**
QueueNumberinteger

弹性网卡的队列数。

  • 如果辅助网卡是已挂载(InUse)状态且没有修改过队列数,则返回实例规格默认的辅助网卡队列数。
  • 如果辅助网卡修改过队列数,则返回修改后的队列数。
  • 如果辅助网卡是未挂载(Available)状态且未修改过队列数,则返回值为空。
  • 主网卡返回实例规格默认的主网卡队列数。
8
PrivateIpSetsarray<object>

PrivateIpSet 组成的集合。

PrivateIpSetobject
PrivateIpAddressstring

实例的私网 IP 地址。

172.17.**.**
Primaryboolean

是否是主私网 IP 地址。可能值:

  • true:主私网 IP
  • false:辅助私网 IP
true
AssociatedPublicIpobject

弹性网卡关联的弹性公网 IP。

PublicIpAddressstring

弹性公网 IP 地址。

116.62.**.**
AllocationIdstring
说明 该参数正在邀测中,暂未开放使用。
null
PrivateDnsNamestring
说明 该参数正在邀测中,暂未开放使用。
DnsTestName
Ipv6Setsarray<object>

弹性网卡已分配的 IPv6 地址集合。

Ipv6Setobject
Ipv6Addressstring

弹性网卡已分配的 IPv6 地址。

2408:4321:180:1701:94c7:bc38:3bfa:****
Ipv4PrefixSetsarray<object>

弹性网卡已分配的 IPv4 前缀集合。

Ipv4PrefixSetobject
Ipv4Prefixstring

弹性网卡已分配的 IPv4 前缀。

192.168.**.0/28
Ipv6PrefixSetsarray<object>

弹性网卡已分配的 IPv6 前缀集合。

Ipv6PrefixSetobject
Ipv6Prefixstring

弹性网卡已分配的 IPv6 前缀。

2001:db8:1234:1a00:****::/80
Tagsarray<object>

标签。

Tagobject
TagValuestring

标签值。

TestValue
TagKeystring

标签键。

TestKey
SecurityGroupIdsarray

所属的安全组集合。

SecurityGroupIdstring

安全组 ID。

sg-bp18kz60mefsicfg****
AssociatedPublicIpobject

弹性网卡辅助私有 IP 地址关联的弹性公网 IP。

PublicIpAddressstring

弹性公网 IP 地址。

116.62.**.**
AllocationIdstring
说明 该参数正在邀测中,暂未开放使用。
null
Attachmentobject
说明 该参数正在邀测中,暂未开放使用。
DeviceIndexinteger
说明 该参数正在邀测中,暂未开放使用。
0
InstanceIdstring
说明 该参数正在邀测中,暂未开放使用。
null
TrunkNetworkInterfaceIdstring
说明 该参数正在邀测中,暂未开放使用。
null
NetworkCardIndexinteger

网卡挂载指定的物理网卡索引。

  • 如果网卡是未挂载(Available)状态或者挂载时未指定索引,则不返回此值。
  • 如果网卡是已挂载(InUse)状态且挂载时指定,此值表示网卡挂载指定的物理网卡索引。
0
DeleteOnReleaseboolean

释放实例时是否保留网卡。可能值:

  • true:不保留。

  • false:保留。

true
SourceDestCheckboolean
说明 该参数正在邀测中,暂未开放使用。
false

示例

正常返回示例

JSON格式

{
  "NextToken": "AAAAAdDWBF2****",
  "PageSize": 1,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 2,
  "NetworkInterfaceSets": {
    "NetworkInterfaceSet": [
      {
        "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": {
          "PrivateIpSet": [
            {
              "PrivateIpAddress": "172.17.**.**",
              "Primary": true,
              "AssociatedPublicIp": {
                "PublicIpAddress": "116.62.**.**",
                "AllocationId": "null"
              },
              "PrivateDnsName": "DnsTestName"
            }
          ]
        },
        "Ipv6Sets": {
          "Ipv6Set": [
            {
              "Ipv6Address": "2408:4321:180:1701:94c7:bc38:3bfa:****"
            }
          ]
        },
        "Ipv4PrefixSets": {
          "Ipv4PrefixSet": [
            {
              "Ipv4Prefix": "192.168.**.0/28"
            }
          ]
        },
        "Ipv6PrefixSets": {
          "Ipv6PrefixSet": [
            {
              "Ipv6Prefix": "2001:db8:1234:1a00:****::/80"
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        },
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-bp18kz60mefsicfg****"
          ]
        },
        "AssociatedPublicIp": {
          "PublicIpAddress": "116.62.**.**",
          "AllocationId": "null"
        },
        "Attachment": {
          "DeviceIndex": 0,
          "InstanceId": "null",
          "TrunkNetworkInterfaceId": "null",
          "NetworkCardIndex": 0
        },
        "DeleteOnRelease": true,
        "SourceDestCheck": false
      }
    ]
  }
}

错误码

HTTP status code错误码错误信息描述
400MissingParameter%s缺失参数,请检查参数是否完整。
400UnsupportedParameter%s不支持参数。
400InvalidParameter%s无效的参数。
400InvalidInstanceID.Malformed%s参数 InstanceId 格式错误。
400InvalidOperation.InvalidEcsState%s实例当前的状态不支持此操作。
400InvalidOperation.InvalidEniState%s弹性网卡当前的状态不支持此操作。
400InvalidOperation.DetachPrimaryEniNotAllowed%s不允许分离实例的主网卡。
400Forbidden.RegionId%s当前地域暂时没有提供该服务。
400InvalidRegionId.MalFormedThe specified parameter RegionId is not valid.指定的 RegionId 不合法。
403InvalidUserType.NotSupported%s您当前的账号不支持此操作。
403Abs.InvalidAccount.NotFound%s您的阿里云账号不存在,或者您的 AccessKey 已经过期。
403Forbidden.NotSupportRAM%s暂不支持RAM用户执行该操作。
403Forbidden.SubUser%s您的账号没有操作此资源的权限,请向主账号申请相关的权限。
403MaxEniCountExceeded%s已超过可以操作的最大弹性网卡数。
403EniPerInstanceLimitExceeded%s实例附加的弹性网卡数量已经达到了最大限度,不能再为实例附加弹性网卡。
403InvalidOperation.AvailabilityZoneMismatch%s该操作无效。
403InvalidOperation.VpcMismatch%s您的操作无效,请确认该操作中的 VPC 与其它参数是否匹配。
403SecurityGroupInstanceLimitExceed%s该安全组内已有的实例数量已达到最大限制。
403InvalidSecurityGroupId.NotVpc%s参数 SecurityGroupId 无效,该安全组的网络类型不是专有网络。
403InvalidOperation.InvalidEniType%s当前弹性网卡的类型不支持此操作。
403InvalidVpc.Empty%s指定的VPC下没有创建交换机,具体信息请参见错误信息%s占位符的实际返回结果。
403InvalidOperation.InvalidEniPageNumber%s-
403InvalidVpc.Indeterminacy%s-
404InvalidEcsId.NotFound%s指定的实例 ID 不存在。
404InvalidEniId.NotFound%s指定的弹性网卡 ID 不存在。
404InvalidVSwitchId.NotFound%s指定的交换机不存在。
404InvalidSecurityGroupId.NotFound%s指定的安全组 ID 不存在。

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2024-09-14OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2024-08-08OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2023-10-09OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2023-01-04OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2021-05-20OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情