调用CreateNetworkInterface创建一个弹性网卡(ENI)。

接口说明

  • 新创建的弹性网卡处于可用(Available)状态。
  • 弹性网卡只支持附加到同一可用区的VPC类型实例。
  • 一个弹性网卡只能附加到一台实例。附加到新实例之前您需要将其与当前实例分离。
  • 弹性网卡重新附加到另一台实例时,其属性不变,网络流量也会重定向到新的实例。
  • 创建弹性网卡时,如果您需要设置IPv6地址,则需要确保指定的交换机开通了IPv6。更多信息,请参见什么是IPv6网关
  • 一个账号在一个阿里云地域内默认最多可创建100个弹性网卡。如果需要更多,请提交工单申请。

调试

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

请求参数

名称 类型 是否必选 示例值 描述
Action String CreateNetworkInterface

系统规定参数。取值:CreateNetworkInterface

RegionId String cn-hangzhou

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

ResourceGroupId String rg-bp67acfmxazb4ph****

资源组ID。您可以调用ListResourceGroups查询资源组信息。

VSwitchId String vsw-bp1s5fnvk4gn2tws03****

指定VPC的交换机ID。弹性网卡的私网IP地址在交换机的IP地址段内的空闲地址中取值。

PrimaryIpAddress String 172.17.**.**

弹性网卡的主私有IP地址。

指定IP必须是在所属交换机的地址段内的空闲地址,不指定则默认随机分配该交换机中的空闲地址。

SecurityGroupId String sg-bp1fg655nh68xyz9i****

加入一个安全组。安全组和弹性网卡必须在同一个专有网络VPC中。

说明 调用接口时,您必须设置SecurityGroupIdSecurityGroupIds.N其中一个,但不支持同时设置。
NetworkInterfaceName String testNetworkInterfaceName

弹性网卡名称。长度为2~128个英文或中文字符。必须以大小字母或中文开头,不能以http://https://开头。可以包含数字、半角冒号(:)、下划线(_)或者短划线(-)。

默认值:空

Description String testDescription

弹性网卡的描述信息。长度为2~256个英文或中文字符,不能以http://https://开头。

默认值:空

SecondaryPrivateIpAddressCount Integer 1

指定私有IP地址数量,让ECS为您自动创建IP地址。

QueueNumber Integer 1

弹性网卡队列数。取值范围:1~2048

绑定弹性网卡时,该值必须少于实例规格支持单块网卡的最大队列数。实例规格的单块网卡最大队列数可以通过DescribeInstanceTypes接口查询MaximumQueueNumberPerEni字段。

默认值:空。在绑定时会采用实例规格的弹性网卡默认队列数,实例规格的弹性网卡默认队列数可以通过DescribeInstanceTypes接口查询SecondaryEniQueueNumber字段。

ClientToken String 123e4567-e89b-12d3-a456-426655440000

保证请求幂等性。从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken只支持ASCII字符,且不能超过64个字符。更多信息,请参见如何保证幂等性

NetworkInterfaceTrafficMode String Standard

弹性网卡的通讯模式。取值范围:

  • Standard:使用TCP通讯模式。
  • HighPerformance:开启ERI(Elastic RDMA Interface)接口,使用RDMA通讯模式。
说明 HighPerformance参数值只支持RDMA增强型实例规格族c7re,且RDMA模式的弹性网卡数量不能超过该实例规格族的限制。c7re正在华北2(北京)可用区K进行邀测。更多信息,请参见实例规格族

默认值:Standard

Ipv6AddressCount Integer 1

为弹性网卡指定随机生成的IPv6地址数量。取值范围:1~10

说明 如果您需要为弹性网卡设置IPv6地址,则必须设置Ipv6Addresses.N或者Ipv6AddressCount的其中一个,但不能同时设置这两个参数。
Tag.N.Key String TestKey

弹性网卡的标签键。N的取值范围:1~20。一旦传入该值,则不允许为空字符串。最多支持128个字符,不能以aliyun和acs:开头,不能包含http://或者https://

Tag.N.Value String TestValue

弹性网卡的标签值。N的取值范围:1~20。一旦传入该值,可以为空字符串。最多支持128个字符,不能以acs:开头,不能包含http://或者https://

SecurityGroupIds.N String sg-bp1fg655nh68xyz9i****

加入一个或多个安全组。安全组和弹性网卡必须在同一个专有网络VPC中。N的取值范围与弹性网卡能够加入安全组配额有关,更多信息,请参见使用限制

说明 调用接口时,您必须设置SecurityGroupIdSecurityGroupIds.N其中一个,但不支持同时设置。
PrivateIpAddress.N String 172.17.**.**

从弹性网卡所属交换机的CIDR地址段内的空闲地址中选择一个或多个辅助私有IP地址。N的取值范围:0~10

说明 分配辅助私有IP地址时,您不能同时指定参数PrivateIpAddress.N和参数SecondaryPrivateIpAddressCount
Ipv6Address.N String 2001:db8:1234:1a00::****

为弹性网卡指定一个或多个IPv6地址。支持设置最多10个IPv6地址,即N的取值范围:1~10

取值示例:Ipv6Address.1=2001:db8:1234:1a00::****

说明 如果您需要为弹性网卡设置IPv6地址,则必须设置Ipv6Addresses.N或者Ipv6AddressCount的其中一个,但不能同时设置这两个参数。

返回数据

名称 类型 示例值 描述
Status String Available

弹性网卡的状态。

Type String Secondary

弹性网卡的类型。

VpcId String vpc-bp1j7w3gc1cexjqd****

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

NetworkInterfaceName String my-eni-name

弹性网卡的名称。

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

弹性网卡的MAC地址。

NetworkInterfaceId String eni-bp14v2sdd3v8htln****

弹性网卡ID。

ServiceID Long 12345678910

弹性网卡对应的虚商ID。

OwnerId String 123456****

弹性网卡的所属账号ID。

ServiceManaged Boolean true

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

VSwitchId String vsw-bp16usj2p27htro3****

VPC的交换机ID。

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

请求ID。

Description String testDescription

弹性网卡的描述信息。

ResourceGroupId String rg-2ze88m67qx5z****

资源组ID。

ZoneId String cn-hangzhou-e

可用区ID。

PrivateIpAddress String 172.17.**.**

弹性网卡的私网IP地址。

SecurityGroupIds Array of String sg-bp18kz60mefsicfg****

所属的安全组集合。

PrivateIpSets Array of PrivateIpSet

PrivateIpSet组成的集合。

PrivateIpSet
PrivateIpAddress String 172.17.**.**

实例的私网IP地址。

Primary Boolean true

是否是主私网IP地址。

Tags Array of Tag

标签。

Tag
TagValue String TestValue

标签值。

TagKey String TestKey

标签键。

Ipv6Sets Array of Ipv6Set

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

Ipv6Set
Ipv6Address String 2001:db8:1234:1a00::****

IPv6地址。

示例

请求示例

https://ecs.aliyuncs.com/?Action=CreateNetworkInterface
&RegionId=cn-hangzhou
&SecurityGroupIds.1=sg-bp18kz60mefsicfg****
&VSwitchId=vsw-bp1s5fnvk4gn2tws03****
&Tag.1.Key=TestKey
&Tag.1.Value=TestValue
&ResourceGroupId=rg-bp67acfmxazb4ph****
&PrimaryIpAddress=172.17.**.**
&NetworkInterfaceName=testNetworkInterfaceName
&Description=testDescription
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&Ipv6AddressCount=1
&<公共请求参数>

正常返回示例

XML格式

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

<CreateNetworkInterfaceResponse>
    <Description>testDescription</Description>
    <Status>Available</Status>
    <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
    <ServiceManaged>false</ServiceManaged>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <ResourceGroupId>rg-2ze88m67qx5z****</ResourceGroupId>
    <ZoneId>cn-hangzhou-e</ZoneId>
    <VSwitchId>vsw-bp16usj2p27htro3****</VSwitchId>
    <NetworkInterfaceName>my-eni-name</NetworkInterfaceName>
    <MacAddress>00:16:3e:12:**:**</MacAddress>
    <NetworkInterfaceId>eni-bp14v2sdd3v8htln****</NetworkInterfaceId>
    <SecurityGroupIds>
        <SecurityGroupId>sg-bp18kz60mefsicfg****</SecurityGroupId>
    </SecurityGroupIds>
    <Type>Secondary</Type>
    <Ipv6Sets>
        <Ipv6Set>
            <Ipv6Address>2001:db8:1234:1a00::****</Ipv6Address>
        </Ipv6Set>
    </Ipv6Sets>
    <VpcId>vpc-bp1j7w3gc1cexjqd****</VpcId>
    <OwnerId>123456****</OwnerId>
    <Tags>
        <Tag>
            <TagKey>TestKey</TagKey>
            <TagValue>TestValue</TagValue>
        </Tag>
    </Tags>
    <PrivateIpSets>
        <PrivateIpSet>
            <PrivateIpAddress>172.17.**.**</PrivateIpAddress>
            <Primary>true</Primary>
        </PrivateIpSet>
    </PrivateIpSets>
</CreateNetworkInterfaceResponse>

JSON格式

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

{
  "Description" : "testDescription",
  "Status" : "Available",
  "PrivateIpAddress" : "172.17.**.**",
  "ServiceManaged" : false,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "ResourceGroupId" : "rg-2ze88m67qx5z****",
  "ZoneId" : "cn-hangzhou-e",
  "VSwitchId" : "vsw-bp16usj2p27htro3****",
  "NetworkInterfaceName" : "my-eni-name",
  "MacAddress" : "00:16:3e:12:**:**",
  "NetworkInterfaceId" : "eni-bp14v2sdd3v8htln****",
  "SecurityGroupIds" : {
    "SecurityGroupId" : [ "sg-bp18kz60mefsicfg****" ]
  },
  "Type" : "Secondary",
  "Ipv6Sets" : {
    "Ipv6Set" : [ {
      "Ipv6Address" : "2001:db8:1234:1a00::****"
    } ]
  },
  "VpcId" : "vpc-bp1j7w3gc1cexjqd****",
  "OwnerId" : "123456****",
  "Tags" : {
    "Tag" : [ {
      "TagKey" : "TestKey",
      "TagValue" : "TestValue"
    } ]
  },
  "PrivateIpSets" : {
    "PrivateIpSet" : [ {
      "PrivateIpAddress" : "172.17.**.**",
      "Primary" : true
    } ]
  }
}

错误码

HttpCode 错误码 错误信息 描述
400 MissingParameter %s 缺失参数,请检查参数是否完整。
400 UnsupportedParameter %s 不支持参数。
400 InvalidParameter %s 无效的参数。
400 InvalidInstanceID.Malformed %s 参数InstanceId格式错误。
400 InvalidOperation.InvalidEcsState %s 实例当前的状态不支持此操作。
400 InvalidOperation.InvalidEniState %s 弹性网卡当前的状态不支持此操作。
400 InvalidOperation.DetachPrimaryEniNotAllowed %s 不允许解绑实例的主网卡。
400 Forbidden.RegionId %s 当前地域暂时没有提供该服务。
400 Duplicate.TagKey The Tag.N.Key contain duplicate key. 标签中存在重复的键,请保持键的唯一性。
400 InvalidTagKey.Malformed The specified Tag.n.Key is not valid. 指定的标签键参数有误。
400 InvalidTagValue.Malformed The specified Tag.n.Value is not valid. 指定的标签值参数有误。
400 JoinedGroupLimitExceed %s 指定资源所能加入的安全组数量达到上限。具体信息请参见错误信息%s占位符的实际返回结果。
400 InvalidPrivateIpAddress.Duplicated Specified private IP address is duplicated. 指定的私网IP已经被使用,请您更换IP再重试。
400 InvalidParameter.Conflict %s 您输入的参数无效,请检查参数之间是否冲突。
403 InvalidUserType.NotSupported %s 您当前的账号不支持此操作。
403 Abs.InvalidAccount.NotFound %s 您的阿里云账号不存在,或者您的AccessKey已经过期。
403 Forbidden.NotSupportRAM %s 暂不支持RAM用户执行该操作。
403 Forbidden.SubUser %s 您的账号没有操作此资源的权限,请向主账号申请相关的权限。
403 MaxEniCountExceeded %s 已超过可以操作的最大弹性网卡数。
403 EniPerInstanceLimitExceeded %s 实例绑定的弹性网卡数量已经达到了最大限度,不能在为实例绑定弹性网卡。
403 InvalidOperation.AvailabilityZoneMismatch %s 该操作无效。
403 InvalidOperation.VpcMismatch %s 您的操作无效,请确认该操作中的VPC与其它参数是否匹配。
403 SecurityGroupInstanceLimitExceed %s 该安全组内已有的实例数量已达到最大限制。
403 InvalidSecurityGroupId.NotVpc %s 参数SecurityGroupId无效,该安全组的网络类型不是专有网络。
403 InvalidOperation.InvalidEniType %s 当前弹性网卡的类型不支持此操作。
403 InvalidVSwitchId.IpNotEnough %s 指定的交换机内IP数量不足。
403 InvalidVSwitchId.IpInvalid %s 指定的私网IP无效。
403 QuotaExceed.Tags %s 标签数超过可以配置的最大数量。
403 InvalidIp.Address %s 指定的IPv6地址无效。
403 InvalidIp.IpRepeated %s 指定的IP重复。
403 MaxEniPrivateIpsCountExceeded %s 指定的ENI分配的辅助私网IP数量超过限制,具体信息请参见错误信息%s占位符的实际返回结果。
403 InvalidOperation.ResourceManagedByCloudProduct %s 云产品托管的安全组不支持修改操作。
403 InvalidParameter.InvalidEniQueueNumber %s 弹性网卡队列数有误,具体信息请参见错误信息%s占位符的实际返回结果。
403 InvalidOperation.MaxEniQueueNumberExceeded %s 弹性网卡队列数超过上限,具体信息请参见错误信息%s占位符的实际返回结果。
403 InvalidOperation.ExceedInstanceTypeQueueNumber %s 弹性网卡队列总数超过上限,具体信息请参见错误信息%s占位符的实际返回结果。
404 InvalidEcsId.NotFound %s 指定的实例ID不存在。
404 InvalidEniId.NotFound %s 指定的弹性网卡ID不存在。
404 InvalidVSwitchId.NotFound %s 指定的交换机不存在。
404 InvalidSecurityGroupId.NotFound %s 指定的安全组ID不存在。
404 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. 资源组并不在记录中。
500 InternalError The request processing has failed due to some unknown error, exception or failure. 内部错误,请重试。如果多次尝试失败,请提交工单。

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