全部产品
Search
文档中心

云服务器 ECS:CreateNetworkInterface

更新时间:Oct 10, 2023

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

接口说明

调用该接口时,请注意:

  • 该接口为同步接口,新创建的弹性网卡为可用(Available)状态,可以直接进行附加操作。
  • 若创建接口返回结果中NetworkInterfaceId为空,请再次尝试创建弹性网卡。
  • 一个弹性网卡只能附加到一台专有网络的实例。
  • 弹性网卡重新附加到另一台实例时,其属性不变,网络流量也会重定向到新的实例。
  • 创建弹性网卡时,如果您需要设置IPv6地址,则需要确保指定的交换机开通了IPv6。更多信息,请参见什么是IPv6网关
  • 一个账号在一个阿里云地域内创建弹性网卡有数量限制。可在ECS管理控制台查看资源配额。具体操作,请参见查看和提升资源配额

调用示例详情参见创建弹性网卡

调试

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

请求参数

名称

类型

是否必选

示例值

描述

Action String CreateNetworkInterface

系统规定参数。取值:CreateNetworkInterface

RegionId String cn-hangzhou

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

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://

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://开头。

默认值:空。

Visible Boolean null
说明 该参数已废弃。
InstanceType String null
说明 该参数已废弃。
BusinessType String null
说明 该参数已废弃。
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。

QueuePairNumber Integer 22
说明 该参数正在邀测中,暂未开放使用。
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的其中一个,但不能同时设置这两个参数。
Ipv6AddressCount Integer 1

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

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

为弹性网卡指定一个或多个IPv4前缀。N的取值范围:1~10。

说明 如果您需要为弹性网卡设置IPv4前缀,则必须设置Ipv4Prefix.N或者Ipv4PrefixCount的其中一个,但不能同时设置这两个参数。
Ipv4PrefixCount Integer 1

为弹性网卡指定一个或多个IPv4前缀。取值范围:1~10。

说明 如果您需要为弹性网卡设置IPv4前缀,则必须设置Ipv4Prefix.N或者Ipv4PrefixCount的其中一个,但不能同时设置这两个参数。
Ipv6Prefix.N String 2001:db8:1234:1a00:****::/80

为弹性网卡指定一个或多个IPv6前缀。N的取值范围:1~10。

说明 如果您需要为弹性网卡设置IPv6前缀,则必须设置Ipv6Prefix.N或者Ipv6PrefixCount的其中一个,但不能同时设置这两个参数。
Ipv6PrefixCount Integer 1

为弹性网卡指定一个或多个IPv6前缀。取值范围:1~10。

说明 如果您需要为弹性网卡设置IPv6前缀,则必须设置Ipv6Prefix.N或者Ipv6PrefixCount的其中一个,但不能同时设置这两个参数。
DeleteOnRelease Boolean true

释放实例时是否保留网卡。取值范围:

  • true:不保留。
  • false:保留。

返回数据

名称

类型

示例值

描述

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****

安全组ID。

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地址。

Ipv4PrefixSets Array of Ipv4PrefixSet

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

Ipv4PrefixSet
Ipv4Prefix String 192.168.**.**/28

IPv4前缀。

Ipv6PrefixSets Array of Ipv6PrefixSet

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

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

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 InvalidOperation.EniCountExceeded The maximum number of eni in a enterprise security group is exceeded. 企业安全组内网卡的数量达到了上限。
400 IncorrectVSwitchStatus The current status of vSwitch does not support this operation. vSwitch当前状态不支持该操作。
400 JoinedGroupLimitExceed %s 指定资源所能加入的安全组数量达到上限。具体信息请参见错误信息%s占位符的实际返回结果。
400 InvalidPrivateIpAddress.Duplicated Specified private IP address is duplicated. 指定的私网 IP 已经被使用,请您更换 IP 再重试。
400 InvalidParameter.Conflict %s 您输入的参数无效,请检查参数之间是否冲突。%s为变量,将根据调用API的实际情况动态返回错误信息。
400 IncorrectVSwitchStatus The current status of virtual switch does not support this operation. 指定的虚拟交换机处于 pending 状态,无法删除。
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 标签数超过可以配置的最大数量。%s为变量,将根据调用API的实际情况动态返回错误信息。
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占位符的实际返回结果。
403 InvalidIp.IpPrefixMaskNotSame The ip prefixes %s are illegal which mask must be same. IP前缀掩码不相同。
403 InvalidIp.IpPrefixMaskInvalid The ip prefixes mask %s is illegal which must be between %s and %s. IP前缀掩码非法,不在有效范围内。
403 InvalidIp.IpPrefixMaskIllegal The ip prefix mask is illegal. IP前缀掩码非法。
403 InvalidIp.IpPrefixIllegal The ip prefixes %s is/are illegal. IP前缀无效,不是cidr格式。
403 InvalidIp.IpPrefixMustInReserveSegment The ip prefix must in vswitch reserve segment. IP前缀无效,不在交换机的预留地址段内。
403 InvalidIp.IpPrefixNotAvailable The ip prefix is/are not available. IP前缀非空闲。
403 InvalidIp.IpPrefixNotStrict The ip prefix must be strict cidr format. IP前缀无效,不是严格的cidr。
403 InvalidVSwitchId.IpPrefixNotEnough The specified vSwitch has not enough ip prefix. 指定的交换机内 IP前缀数量不足。
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. 资源组并不在记录中。
404 InvalidOperation.AddressAlreadyAllocated The specified ip address has been already allocated. 指定的IP地址已经被使用。
404 InvalidOperation.SlaveEniMustHaveBondingEni Create slave eni must have bonding eni first. 创建Slave网卡前必须创建Bond网卡。
404 InvalidOperation.VSwitchCidrReservationNotExist The specified vSwitch has no cidr reservation. 指定的交换机没有可用的预留段。
500 InternalError The request processing has failed due to some unknown error, exception or failure. 内部错误,请重试。
500 InvalidOperation.RegionNotSupportIpPrefix The current region does not support ip prefix. 该地域不支持分配IP前缀。

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