> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/cn/zlb/load-balancer-instance/createloadbalancer.md).
# CreateLoadBalancer
## 1. 接口描述
本接口(CreateLoadBalancer)用于创建负载均衡器实例。
{% hint style="info" %}
**注意事项**
* 可以通过调用 [DescribeLoadBalancerRegions](/api-reference/cn/zlb/location/describeloadbalancerregions.md) 查看支持购买负载均衡的地域。
* 本接口为异步接口，接口成功返回后，可调用 [DescribeLoadBalancers](/api-reference/cn/zlb/load-balancer-instance/describeloadbalancers.md) 查询负载均衡实例的状态。其中状态为`RUNNING`则代表创建成功。
* 当前只支持为ZEC服务器创建负载均衡实例。
* 只支持后付费负载均衡实例创建。
* 创建负载均衡实例时，请确保该VPC下存在满足`ipStackType`要求的子网，并且子网内至少有2个可用地址供分配。
* 通过`eipIds`指定已有EIP时，EIP在负载均衡实例创建完成（状态变为`RUNNING`）后才完成绑定，绑定结果可通过 [DescribeEips](/api-reference/cn/zec/elastic-ip/describeeips.md) 查询。
{% endhint %}
## 2. 请求参数
以下请求参数列表仅列出了接口中需要的请求参数
| 参数名称 | 必选 | 类型 | 描述 |
| --------------------- | -- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| regionId | 是 | String | 区域节点ID。
可通过调用 DescribeRegions 获取。
|
| loadBalancerName | 是 | String | 负载均衡实例名称。
长度为1～64个字符。
可选值范围：\[1.0, +)
|
| vpcId | 否 | String | 负载均衡后端服务器所属的VPC网络ID。
vpcId和subnetId至少指定一个。
仅指定subnetId时，取该子网所属的VPC。
可通过调用 DescribeVpcs 获取。
|
| subnetId | 否 | String | 子网ID。
可以通过调用 DescribeSubnets 获取。
vpcId和subnetId至少指定一个。
该子网需与regionId同区域，同时指定vpcId时还须属于该VPC。
ipStackType为IPv4时该子网需支持IPv4，此参数可不指定（由系统在该VPC内选择）；为IPv6时该子网需含公网IPv6网段（内网IPv6不满足），且此参数必填——公网IPv6 VIP与健康检查段都从该子网分配，不指定将返回MISSING\_PARAMETER。
|
| healthCheckPrivateIps | 否 | Array of String | 健康检查内网源IP地址，数量必须为2。
指定subnetId时，不填则从该子网中随机分配2个可用的内网IPv4地址作为健康检查源IP，每个负载均衡实例占用2个地址，该子网剩余可用内网IPv4地址不足时将返回INVALID\_SUBNET\_IPV4\_INSUFFICIENT，分配结果可调用 DescribeLoadBalancers 查询。
不指定subnetId时，此参数无效。
仅ipStackType为IPv4时可指定：为IPv6时健康检查段由系统从该子网的公网IPv6网段自动分配，指定本参数将返回INVALID\_PARAMETER\_CONFLICT。
|
| ipStackType | 否 | [LoadBalancerIpStackType](/api-reference/cn/zlb/datastructure.md#loadbalanceripstacktype) | IP堆栈类型。
负载均衡实例只支持单栈，即IPv4或IPv6，不支持双栈。
指定为IPv6时不支持配置公网网络参数（internetChargeType、networkLineType、bandwidthMbps、trafficPackageSize、bandwidthClusterId），也不能指定eipIds——EIP均为IPv4，IPv6负载均衡的公网地址通过 AssignLoadBalancerIpv6 接口单独分配。
默认值：IPv4
|
| eipIds | 否 | Array of String | 指定绑定到新建负载均衡实例的已有弹性公网IP的ID列表。
支持单IP（掩码/32）与网段类型的EIP，可调用 DescribeEips 查询。
所有EIP需与regionId同区域且处于未绑定状态。
指定此参数时，internetChargeType、networkLineType、bandwidthMbps、trafficPackageSize、bandwidthClusterId均不生效，系统不再为该实例新建EIP，且number只能为1。
仅ipStackType为IPv4时可指定。
|
| internetChargeType | 否 | [InternetChargeType](/api-reference/cn/zlb/datastructure.md#internetchargetype) | IP网络计费模式。
指定eipIds时该参数不生效。
|
| ipNetworkType \[已废弃] | 否 | [EipNetworkType](/api-reference/cn/zlb/datastructure.md#eipnetworktype) | IP的网络类型。
已废弃，请使用networkLineType。
|
| networkLineType | 否 | [NetworkLineType](/api-reference/cn/zlb/datastructure.md#networklinetype) | IP的网络类型。 |
| bandwidthMbps | 否 | Integer | EIP的最大出带宽。单位为Mbps。最大限制通常为10000，如果有额外要求，请联系Support。当internetChargeType为ByBandwidth时，此参数必填。
可选值范围：\[1, +)
|
| trafficPackageSize | 否 | Float | 流量包大小。
指定此参数时，IP网络计费模式(internetChargeType)需为ByTrafficPackage，否则该参数不生效。
仅当计费周期为月时支持设置，小时计费不支持。
可选值范围：\[0.0, 999999.0]
|
| bandwidthClusterId | 否 | String | 共享带宽包ID。
指定此参数时，IP网络计费模式(internetChargeType)需为BandwidthCluster，否则该参数不生效。
|
| resourceGroupId | 否 | String | 资源组ID。
如果不指定，则会创建在默认资源组。
|
| number | 否 | Integer | 创建负载均衡的个数。
默认值：1
|
| marketingOptions | 否 | [MarketingInfo](/api-reference/cn/zlb/datastructure.md#marketinginfo) | 市场活动的相关信息。 |
| tags | 否 | [TagAssociation](/api-reference/cn/zlb/datastructure.md#tagassociation) | 创建负载均衡时关联的标签。
注意：·关联标签键不能重复。
|
| securityGroupId | 否 | String | 负载均衡实例绑定的安全组ID。
可以通过调用 DescribeSecurityGroups 获取。
|
## 3. 响应结果
| 参数名称 | 类型 | 描述 |
| --------------- | --------------- | -------------------------------------------------------- |
| requestId | String | 唯一请求 ID。
每次请求都会返回。定位问题时需要提供该次请求的 requestId。
|
| orderNumber | String | 下单编号。 |
| loadBalancerIds | Array of String | 由负载均衡实例唯一ID组成的集合。 |
## 4. 代码示例
{% tabs %}
{% tab title="示例" %}
**1. 创建一个公网负载均衡实例。IP计费方式为固定带宽。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request：
{
"regionId" : "asia-east-1",
"vpcId" : "",
"securityGroupId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"trafficPackageSize" : null,
"bandwidthClusterId" : "",
"number" : 1
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**2. 不指定`vpcId`，仅指定`subnetId`：负载均衡实例归属该子网所属的VPC，并从该子网中随机分配2个内网IPv4地址作为健康检查源IP。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request：
{
"regionId" : "asia-east-1",
"subnetId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"number" : 1
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**3. 指定已有的弹性公网IP（EIP）创建负载均衡实例，不再新建EIP。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request：
{
"regionId" : "asia-east-1",
"vpcId" : "",
"loadBalancerName" : "sample",
"eipIds" : ["", ""],
"number" : 1
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
**4. 创建负载均衡实例，并使用POC代金券。如果系统不存在POC代金券，创建流程会失败。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateLoadBalancer
Request：
{
"regionId" : "asia-east-1",
"vpcId" : "",
"securityGroupId" : "",
"loadBalancerName" : "sample",
"internetChargeType" : "ByBandwidth",
"networkLineType" : "PremiumBGP",
"bandwidthMbps" : 2,
"number" : 1,
"marketingOptions" : {
"usePocVoucher" : true
}
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"orderNumber": "",
"loadBalancerIds": [""]
}
}
```
{% endtab %}
{% endtabs %}
## 5. 开发者工具
Zenlayer Cloud API 2.0 提供了配套的[开发工具集（SDK）](/api-reference/cn/api-introduction/toolkit.md)，未来会陆续支持更多开发语言，方便快速接入和使用Zenlayer的产品和服务。
## 6. 错误码
下面包含业务逻辑中遇到的错误码，其他错误码见[公共错误码](/api-reference/cn/api-introduction/instruction/commonerrorcode.md)
| HTTP状态码 | 错误码 | 说明 |
| ------- | --------------------------------------------------------------------- | --------------------------------------- |
| 404 | INVALID\_EIP\_NOT\_FOUND | EIP不存在。 |
| 400 | INVALID\_IP\_BROADCAST\_ADDRESS | IP为广播地址不可用。 |
| 400 | INVALID\_IP\_FIRST\_ADDRESS | IP为网关地址不可用。 |
| 400 | INVALID\_IP\_NETWORK\_ADDRESS | IP为网络地址不可用。 |
| 400 | INVALID\_IP\_OUT\_OF\_RANGE | IP地址不合法，不属于CIDR范围。 |
| 400 | INVALID\_REGION\_MISMATCH | EIP与目标资源不在同一区域。 |
| 404 | INVALID\_REGION\_NOT\_FOUND | 区域不存在。 |
| 404 | INVALID\_SECURITY\_GROUP\_NOT\_FOUND | 安全组不存在。 |
| 409 | INVALID\_SUBNET\_IPV4\_INSUFFICIENT | Subnet下可用的IPv4数量不足。 |
| 409 | INVALID\_SUBNET\_IPV6\_INSUFFICIENT | Subnet下可用的IPv6数量不足。 |
| 400 | INVALID\_SUBNET\_NOT\_BELONG\_TO\_VPC | 指定的子网不属于VPC。 |
| 404 | INVALID\_SUBNET\_NOT\_FOUND | 子网不存在。 |
| 409 | INVALID\_SUBNET\_PRIVATE\_IPV4\_IN\_USED | 内定的内网IP已经被使用。 |
| 404 | INVALID\_VPC\_NOT\_FOUND | VPC不存在。 |
| 400 | OPERATION\_DENIED\_EIP\_ASSIGNED\_LIMIT\_EXCEEDED | EIP绑定超过数量限制。 |
| 400 | OPERATION\_DENIED\_EIP\_INSUFFICIENT | 公网IP的库存不足，无法操作。 |
| 400 | OPERATION\_DENIED\_EIP\_IS\_DEFAULT | 默认公网IP无法解绑。 |
| 400 | OPERATION\_DENIED\_EIP\_IS\_NOT\_UN\_ASSIGN | EIP已被占用（非未绑定状态），无法绑定。 |
| 400 | OPERATION\_DENIED\_EIP\_QUOTA\_LIMIT\_EXCEEDED | EIP数量超过配额限制。 |
| 500 | OPERATION\_DENIED\_EIP\_STATUS\_NOT\_SUPPORT | EIP状态不支持此操作。 |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT | 子网堆栈类型不支持。 |
| 400 | OPERATION\_DENIED\_SUBNET\_TYPE\_NOT\_SUPPORT\_IPV4 | 子网堆栈类型不包括IPv4。 |
| 400 | OPERATION\_DENIED\_SUBNET\_NOT\_SUPPORT\_PUBLIC\_IPV6 | 子网没有公网IPv6网段。 |
| 409 | OPERATION\_DENIED\_NO\_AVAILABLE\_SUBNET | VPC下不存在有效子网，无法操作。 |
| 400 | INVALID\_PARAMETER\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP不支持自定义流量包大小，需传0或不传。 |
| 400 | OPERATION\_DENIED\_FIXED\_BANDWIDTH\_NOT\_SUPPORTED\_FOR\_PATH\_BASED | PathBasedBandwidthIP不支持固定带宽计费。 |
| 400 | OPERATION\_DENIED\_FLOW\_PACKAGE\_NOT\_SUPPORTED\_HOUR\_PERIOD | 当前产品周期为小时计费，不支持设置保底流量包大小。 |