文档首页/ 企业交换机 ESW/ API参考/ 企业交换机/ 创建ESW实例 - CreateInstance

更新时间：2025-11-20 GMT+08:00

查看PDF

创建ESW实例 - CreateInstance

功能介绍

您可通过调用本接口创建一个ESW实例。该接口是一个异步接口，当前创建ESW实例的请求下发成功后，会响应job_id以及实例ID等信息，需要通过调用查询任务的执行状态查询job状态。

调试

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

授权信息

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

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

URI

POST /v3/{project_id}/l2cg/instances

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：ESW实例所属项目ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
instance	是	CreatePostpaidInstanceOption object	参数解释：创建实例的请求体。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表3 CreatePostpaidInstanceOption
参数	是否必选	参数类型	描述
availability_zones	是	AvailabilityZones object	参数解释：ESW实例节点所在的可用区。约束限制：不涉及。取值范围：当前区域可用区。默认取值：不涉及。
charge_infos	是	PostPaidChargeInfos object	参数解释：计费信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
flavor_ref	是	String	参数解释：ESW实例规格。约束限制：不涉及。取值范围：参考flavor list接口响应。默认取值：不涉及。
ha_mode	是	String	参数解释：ESW实例的高可用模式。约束限制：当前只支持设置ha。取值范围：ha。默认取值：不涉及。
name	是	String	参数解释：ESW实例名称。约束限制：长度范围为1~64个字符。名称由中文、英文字母、数字、下划线（_）、中划线（-）、点（.）组成。取值范围：不涉及。默认取值：不涉及。
tunnel_info	是	TunnelInfoOption object	参数解释：本端隧道信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：ESW实例描述信息。约束限制：长度范围为0~255个字符。不能包含“<”和“>”。取值范围：不涉及。默认取值：不涉及。

表4 AvailabilityZones
参数	是否必选	参数类型	描述
primary	是	String	参数解释：ESW实例默认主节点所在的可用区。约束限制：1-128字符。取值范围：当前区域可用区id。默认取值：不涉及。
standby	是	String	参数解释：ESW实例默认备节点所在的可用区。约束限制：1-128字符。取值范围：当前区域可用区id。默认取值：不涉及。

表5 PostPaidChargeInfos
参数	是否必选	参数类型	描述
charge_mode	是	String	参数解释：付费方式（后付费，即按需付费）。约束限制：不涉及。取值范围：postPaid,后付费，即按需付费。默认取值：不涉及。

表6 TunnelInfoOption
参数	是否必选	参数类型	描述
vpc_id	是	String	参数解释：ESW所在VPC资源ID。约束限制：需要使用本租户下可操作的VPC资源的ID。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
virsubnet_id	是	String	参数解释：ESW所在隧道子网ID。约束限制：需要使用本租户下可操作的子网资源的ID；此值即为子网详情中的“网络ID”参数值。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
tunnel_ip	否	String	参数解释：ESW的隧道IP。约束限制：不能与已存在的子网IP冲突。取值范围：标准的IPv4格式，例：192.168.1.1。默认取值：不涉及。

响应参数

状态码：201

表7 响应Body参数
参数	参数类型	描述
request_id	String	参数解释：请求的唯一标识。约束限制：UUID格式。取值范围：不涉及。默认取值：不涉及。
instance	Instance object	参数解释：创建实例的响应体。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
job_id	String	参数解释：任务的唯一标识。约束限制：带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。

表8 Instance
参数	参数类型	描述
id	String	参数解释：ESW实例的唯一标识。约束限制：带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
name	String	参数解释：ESW实例名称。约束限制：长度范围为1~64个字符。名称由中文、英文字母、数字、下划线（_）、中划线（-）、点（.）组成。取值范围：不涉及。默认取值：不涉及。
project_id	String	参数解释：ESW实例所属项目ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
region	String	参数解释：ESW实例所属region的ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
flavor_ref	String	参数解释：ESW实例规格。约束限制：不涉及。取值范围：参考flavor list接口响应。默认取值：不涉及。
ha_mode	String	参数解释：ESW实例的高可用模式。约束限制：当前只支持设置ha。取值范围：ha。默认取值：不涉及。
status	String	参数解释：ESW实例的状态。约束限制：不涉及。取值范围： active：运行中 failed：创建失败 abnormal：异常 build：创建中 frozen：已冻结默认取值：不涉及。
created_at	String	参数解释：ESW实例创建时间。约束限制：UTC时间，格式为yyyy-MM-ddTHH:mm:ss。取值范围：不涉及。默认取值：不涉及。
updated_at	String	参数解释：ESW实例更新时间。约束限制：UTC时间，格式为yyyy-MM-ddTHH:mm:ss。取值范围：不涉及。默认取值：不涉及。
description	String	参数解释：ESW实例描述信息。约束限制：长度范围为0~255个字符。不能包含“<”和“>”。取值范围：不涉及。默认取值：不涉及。
tunnel_info	TunnelInfoResult object	参数解释：本端隧道信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
charge_infos	PostPaidChargeInfos object	参数解释：计费信息。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
availability_zones	AvailabilityZones object	参数解释：ESW实例节点所在的可用区。约束限制：不涉及。取值范围：当前区域可用区。默认取值：不涉及。

表9 TunnelInfoResult
参数	参数类型	描述
vpc_id	String	参数解释：ESW所在VPC资源ID。约束限制：需要使用本租户下可操作的VPC资源的ID。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
virsubnet_id	String	参数解释：ESW所在隧道子网ID。约束限制：需要使用本租户下可操作的子网资源的ID；此值即为子网详情中的“网络ID”参数值。带“-”的UUID格式。取值范围：不涉及。默认取值：不涉及。
tunnel_ip	String	参数解释：ESW实例的本端隧道IP。约束限制：不能与已存在的子网IP冲突。取值范围：标准的IPv4格式，例：192.168.1.1。默认取值：不涉及。
tunnel_port	Integer	参数解释：ESW实例的隧道端口。约束限制：不涉及。取值范围：4789。默认取值：不涉及。
tunnel_type	String	参数解释：ESW实例的隧道协议类型。约束限制：不涉及。取值范围：vxlan。默认取值：不涉及。

**表10** PostPaidChargeInfos
参数	参数类型	描述
charge_mode	String	参数解释：付费方式（后付费，即按需付费）。约束限制：不涉及。取值范围：postPaid,后付费，即按需付费。默认取值：不涉及。

**表11** AvailabilityZones
参数	参数类型	描述
primary	String	参数解释：ESW实例默认主节点所在的可用区。约束限制：1-128字符。取值范围：当前区域可用区id。默认取值：不涉及。
standby	String	参数解释：ESW实例默认备节点所在的可用区。约束限制：1-128字符。取值范围：当前区域可用区id。默认取值：不涉及。

请求示例

POST https://{endpoint}/v3/b2782e6708b8475c993e6064bc456bf8/l2cg/instances

{
  "instance" : {
    "availability_zones" : {
      "primary" : "az1",
      "standby" : "az2"
    },
    "charge_infos" : {
      "charge_mode" : "postPaid"
    },
    "flavor_ref" : "l2cg.small.ha",
    "ha_mode" : "ha",
    "name" : "esw-88d4",
    "tunnel_info" : {
      "vpc_id" : "6ae030de-f630-476e-8284-7bcfbd94929d",
      "virsubnet_id" : "6c32956f-eb3a-4521-8b83-d5a2d5f9b978"
    },
    "description" : ""
  }
}

响应示例

状态码：201

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

{
  "request_id" : "2f1bdab599c96eb0b47a5e99ba9574bb",
  "job_id" : "9bd12abc-17ba-4e40-9484-f4e97ee7ff59",
  "instance" : {
    "name" : "esw-88d4",
    "id" : "87fea8df-3e0d-473a-a1bd-e6a76157f4ce",
    "region" : "cn-north-213",
    "status" : "build",
    "description" : null,
    "created_at" : "2025-07-28T03:45:05Z",
    "updated_at" : "2025-07-28T03:45:05Z",
    "project_id" : "dd9e484e058b48e18b820948dcbd480e",
    "flavor_ref" : "l2cg.small.ha",
    "ha_mode" : "ha",
    "availability_zones" : {
      "standby" : "az1",
      "primary" : "az2"
    },
    "charge_infos" : {
      "charge_mode" : "postPaid"
    },
    "tunnel_info" : {
      "vpc_id" : "6ae030de-f630-476e-8284-7bcfbd94929d",
      "virsubnet_id" : "6c32956f-eb3a-4521-8b83-d5a2d5f9b978",
      "tunnel_ip" : "192.168.7.95",
      "tunnel_port" : 4789,
      "tunnel_type" : "vxlan"
    }
  }
}

状态码

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

错误码

请参见错误码。

父主题： 企业交换机

上一篇：企业交换机

下一篇：删除ESW实例 - DeleteInstance

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

盘古Doer提问云社区提问