创建二层连接 - CreateConnection

功能介绍

当您的ESW实例创建成功后，您可以通过调用此接口在该实例上创建一个二层连接。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
esw:connection:create	Write	-	-	-	-

URI

POST /v3/{project_id}/l2cg/instances/{instance_id}/connections

表1 路径参数
参数	是否必选	参数类型	描述
instance_id	是	String	参数解释：ESW实例的唯一标识。约束限制：带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
project_id	是	String	参数解释：ESW实例所属项目ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
connection	是	CreateConnectionOption object	参数解释：创建二层连接的请求体。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表3 CreateConnectionOption
参数	是否必选	参数类型	描述
fixed_ips	否	Array of strings	参数解释：下联面网口主备IP；ESW实例在本端二层子网中占用的主备接口IP。约束限制：字符串列表，只能设置两个字符串，且每个字符串内容应该是标准IPv4格式；IP必须在二层子网网段范围内。取值范围：不涉及。默认取值：不涉及。
name	是	String	参数解释：二层连接的名称。约束限制：长度范围为1~64个字符。名称由中文、英文字母、数字、下划线（_）、中划线（-）、点（.）组成。取值范围：不涉及。默认取值：不涉及。
remote_infos	是	Array of RemoteInfosOption objects	参数解释：远端隧道信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
virsubnet_id	是	String	参数解释：二层连接关联的二层子网ID。约束限制：需要使用本租户下可操作的子网资源的ID；此值即为子网详情中的“网络ID”参数值。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
vpc_id	是	String	参数解释：ESW所在VPC资源ID。约束限制：需要使用本租户下可操作的VPC资源的ID。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。

表4 RemoteInfosOption
参数	是否必选	参数类型	描述
segmentation_id	是	Integer	参数解释：二层连接的隧道号，对应VXLAN网络标识VNI。约束限制：需与对端VXLAN设置的VNI保持一致。取值范围：1-16777216。默认取值：不涉及。
tunnel_ip	是	String	参数解释：ESW实例的远端隧道IP。约束限制：需与对端VXLAN设置的VTEP IP保持一致。取值范围：标准的IPv4格式，例：192.168.1.1。默认取值：不涉及。
tunnel_port	否	Integer	参数解释：二层连接的远端隧道端口。约束限制：不涉及。取值范围：4789。默认取值：不涉及。

响应参数

状态码：201

表5 响应Body参数
参数	参数类型	描述
request_id	String	参数解释：请求的唯一标识。约束限制：UUID格式。取值范围：不涉及。默认取值：不涉及。
connection	Connection object	参数解释：创建二层连接的响应体。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表6 Connection
参数	参数类型	描述
fixed_ips	Array of strings	参数解释：下联面网口主备IP；ESW实例在本端二层子网中占用的主备接口IP。约束限制：字符串列表，只能设置两个字符串，且每个字符串内容应该是标准IPv4格式；IP必须在二层子网网段范围内。取值范围：不涉及。默认取值：不涉及。
id	String	参数解释：二层连接的唯一标识。约束限制：带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
instance_id	String	参数解释：ESW实例的唯一标识。约束限制：带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
name	String	参数解释：二层连接的名称。约束限制：长度范围为1~64个字符。名称由中文、英文字母、数字、下划线（_）、中划线（-）、点（.）组成。取值范围：不涉及。默认取值：不涉及。
project_id	String	参数解释：ESW实例所属项目ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
remote_infos	Array of RemoteInfosResult objects	参数解释：远端隧道信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
status	String	参数解释：二层连接的状态。约束限制：不涉及。取值范围： pending：准备中 connected：已连接 disconnect：未连接 failed：创建失败 abnormal：异常默认取值：不涉及。
virsubnet_id	String	参数解释：二层连接关联的二层子网ID。约束限制：需要使用本租户下可操作的子网资源的ID；此值即为子网详情中的“网络ID”参数值。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
vpc_id	String	参数解释：ESW所在VPC资源ID。约束限制：需要使用本租户下可操作的VPC资源的ID。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
created_at	String	参数解释：二层连接创建时间。约束限制：UTC时间，格式为yyyy-MM-ddTHH:mm:ss。取值范围：不涉及。默认取值：不涉及。
updated_at	String	参数解释：二层连接更新时间。约束限制：UTC时间，格式为yyyy-MM-ddTHH:mm:ss。取值范围：不涉及。默认取值：不涉及。

表7 RemoteInfosResult
参数	参数类型	描述
segmentation_id	Integer	参数解释：二层连接的隧道号，对应VXLAN网络标识VNI。约束限制：需与对端VXLAN设置的VNI保持一致。取值范围：1-16777216。默认取值：不涉及。
tunnel_ip	String	参数解释：ESW实例的远端隧道IP。约束限制：不能与已存在的子网IP冲突。取值范围：标准的IPv4格式，例：192.168.1.1。默认取值：不涉及。
tunnel_port	Integer	参数解释：二层连接的远端隧道端口。约束限制：不涉及。取值范围：4789。默认取值：不涉及。
tunnel_type	String	参数解释：ESW实例的隧道协议类型。约束限制：不涉及。取值范围：vxlan。默认取值：不涉及。

请求示例

POST https://{endpoint}/v3/dd9e484e058b48e18b820948dcbd480e/l2cg/instances/87fea8df-3e0d-473a-a1bd-e6a76157f4ce/connections

{
  "connection" : {
    "virsubnet_id" : "2c649856-0d44-400c-8194-f6d67603e0eb",
    "fixed_ips" : [ "192.168.0.11", "192.168.0.12" ],
    "name" : "l2conn-7a0c",
    "remote_infos" : [ {
      "tunnel_port" : 4789,
      "segmentation_id" : 7127,
      "tunnel_ip" : "192.168.111.111"
    } ],
    "vpc_id" : "6ae030de-f630-476e-8284-7bcfbd94929d"
  }
}

响应示例

状态码：201

POST操作正常返回，更多状态码请参见状态码。

{
  "request_id" : "318ad7fa0bae74f2b0a22b44d6740309",
  "connection" : {
    "name" : "l2conn-7a0c",
    "id" : "555fe9b7-62fe-48c6-a73d-a62413f110f1",
    "status" : "pending",
    "created_at" : "2025-07-28T08:39:59Z",
    "updated_at" : "2025-07-28T08:39:59Z",
    "project_id" : "dd9e484e058b48e18b820948dcbd480e",
    "instance_id" : "87fea8df-3e0d-473a-a1bd-e6a76157f4ce",
    "vpc_id" : "6ae030de-f630-476e-8284-7bcfbd94929d",
    "virsubnet_id" : "2c649856-0d44-400c-8194-f6d67603e0eb",
    "fixed_ips" : [ "192.168.0.11", "192.168.0.12" ],
    "remote_infos" : [ {
      "segmentation_id" : 7127,
      "tunnel_ip" : "192.168.111.111",
      "tunnel_port" : 4789,
      "tunnel_type" : "vxlan"
    } ]
  }
}