> 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-listener/createlistener.md). # CreateListener ## 1. 接口描述 本接口(CreateListener)用于创建负载均衡的监听器。 {% hint style="info" %} **注意事项** * `algoOpts`（无状态转发）与`persistent`（会话保持）之所以互斥，是因为无状态转发逐包哈希转发、不维护连接跟踪表，无法保证同一客户端命中同一后端。 {% endhint %} ## 2. 请求参数 以下请求参数列表仅列出了接口中需要的请求参数 | 参数名称 | 必选 | 类型 | 描述 | | -------------- | -- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | loadBalancerId | 是 | String |

负载均衡实例ID。

可通过调用 DescribeLoadBalancers 获取。

| | listenerName | 是 | String |

要创建的监听器名称。

仅支持字母、数字、连字符(-)和句点(.)，且开头和结尾必须是字母或数字。

| | protocol | 是 | [ListenerProtocol](/api-reference/cn/zlb/datastructure.md#listenerprotocol) | 监听器协议。 | | scheduler | 是 | [ListenerScheduler](/api-reference/cn/zlb/datastructure.md#listenerscheduler) | 监听器的调度算法。 | | port | 是 | String |

监听器端口。

多个端口使用半角逗号（,）分隔。

当端口是范围时用-连接，例如：10000-10005。

端口的取值范围为0～65535，0代表全范围端口。

请注意端口不能和该监听器的其他端口有重叠。

范围端口与全端口在配额计算中均按1个端口计。

连续的单端口会被自动合并为区间端口后再保存和返回，例如1,2,3,4,5会被保存为1-5。

| | healthCheck | 否 | [HealthCheck](/api-reference/cn/zlb/datastructure.md#healthcheck) |

健康检查相关参数。

不传该参数、或将healthCheck.enabled设为false时，关闭健康检查。

| | kind | 否 | [LoadBalancerKind](/api-reference/cn/zlb/datastructure.md#loadbalancerkind) |

工作模式。

若该负载均衡器已有监听器，默认沿用其工作模式；否则根据负载均衡实例所在的区域设定默认值（默认值可能为DNAT、FNAT）。

同一负载均衡器下所有监听器工作模式必须一致，DR模式下监听器不支持设置为全端口（0）。

负载均衡实例的ipStackType为IPv6时只支持DR，不指定时默认为DR。

| | persistent | 否 | Integer |

会话保持时间，单位秒。

与algoOpts（调度算法高级选项）互斥：该监听器设置了algoOpts时不可传非0值。

可选值范围：\[0, +)

| | idleTimeout | 否 | Integer |

空闲超时时间，单位秒。

可选值范围：\[60, +)

默认值：300

| | algoOpts | 否 | [ListenerAlgoOpts](/api-reference/cn/zlb/datastructure.md#listeneralgoopts) |

调度算法高级选项。

仅当工作模式（kind）为DR且调度算法（scheduler）为mh时可设置，其它组合传入将报错。

创建时传None等价于不设置该字段。

开启后与会话保持（persistent）互斥，不可同时设置非0值。

| ## 3. 响应结果 | 参数名称 | 类型 | 描述 | | ---------- | ------ | -------------------------------------------------------- | | requestId | String |

唯一请求 ID。

每次请求都会返回。定位问题时需要提供该次请求的 requestId。

| | listenerId | String | 创建的监听器ID。 | ## 4. 代码示例 {% tabs %} {% tab title="示例" %} **1. 创建一个TCP负载均衡监听器，监听8080-9000以及8000端口。不开启健康检查。** ```json POST /api/v2/zlb HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateListener Request： { "loadBalancerId" : "", "listenerName" : "sample", "protocol" : "TCP", "scheduler" : "mh", "port" : "8080-9000,8000", "persistent": 60, "idleTimeout": 60 } Response： { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3", "response": { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3", "listenerId": "" } } ``` **2. 创建一个TCP负载均衡监听器的同时设置健康检查信息。** ```json POST /api/v2/zlb HTTP/1.1 Host: console.zenlayer.com Content-Type: application/json X-ZC-Action: CreateListener Request： { "loadBalancerId" : "", "listenerName" : "sample", "protocol" : "TCP", "scheduler" : "mh", "healthCheck": { "enabled": true, "checkType": "HTTP_GET", "checkPort": null, "checkDelayLoop": 3, "checkConnTimeout": 2, "checkRetry": 2, "checkDelayTry": 2, "checkHttpGetUrl": "/health", "checkHttpStatusCode": 200 }, "port" : "8080", "persistent": 60, "idleTimeout": 60 } Response： { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3", "response": { "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3", "listenerId": "" } } ``` {% 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状态码 | 错误码 | 说明 | | ------- | ---------------------------------------------------- | -------------------------------------- | | 400 | INVALID\_ALGO\_OPTS\_NOT\_SUPPORTED | 调度算法高级选项仅在转发模式为DR且调度算法为MH时支持设置。 | | 400 | INVALID\_ALGO\_OPTS\_PERSISTENT\_CONFLICT | 调度算法高级选项（无状态转发）与会话保持不能同时开启。 | | 409 | INVALID\_BACKEND\_INSTANCE\_LISTENER\_EXIST | 后端服务器已存在。 | | 409 | INVALID\_BACKEND\_INSTANCE\_MULTIPLE | 后端服务器重复。 | | 400 | INVALID\_BACKEND\_IP\_ADDRESS | 后端服务器的内网IP未找到相关实例。 | | 409 | INVALID\_BACKEND\_IP\_ZBG\_REQUIRED | 加入的后端服务器IP需要VPC建立边界网关。 | | 400 | INVALID\_BACKEND\_SERVER\_IP\_INVALID | 后端服务器IP不合法，必须为内网IP地址。 | | 409 | INVALID\_BACKEND\_SERVER\_IP\_REPEAT | 后端服务器IP重复。 | | 400 | INVALID\_BACKEND\_SERVER\_PORT | DR模式、全端口或监听多个端口无法指定后端服务器端口。 | | 400 | INVALID\_INSTANCE\_IP\_ADDRESS | 实例的内网IP不合法。 | | 404 | INVALID\_INSTANCE\_NOT\_FOUND | 服务器实例不存在。 | | 404 | INVALID\_LB\_LISTENER\_NOT\_FOUND | 监听器不存在。 | | 404 | INVALID\_LB\_NOT\_FOUND | 负载均衡器不存在。 | | 400 | INVALID\_LB\_STATUS | 当前负载均衡器状态无法进行操作。 | | 409 | INVALID\_LISTENER\_KIND\_CONFLICT | 监听器工作模式与LB下已有监听器不一致。 | | 400 | INVALID\_LISTENER\_KIND\_DR\_ALL\_PORT\_NOT\_SUPPORT | DR模式的监听器不支持设置为全端口(0)。 | | 400 | INVALID\_LISTENER\_KIND\_NOT\_SUPPORT | 指定的监听器类型在该区域不支持。 | | 409 | INVALID\_LISTENER\_PORT\_CONFLICT | 端口和其他监听器端口冲突。 | | 409 | INVALID\_LISTENER\_PORT\_CONFLICT\_SELF | 当前配置的端口不合法，有冲突。 | | 400 | INVALID\_LISTENER\_QUOTA\_EXCEED | 负载均衡器的监听器数量超过限制。 | | 400 | INVALID\_PORT\_FORMAT\_ERROR | 端口格式不合法。 | | 400 | INVALID\_PORT\_RANGE | 端口范围超出临界值。 | | 400 | INVALID\_RS\_QUOTA\_EXCEED\_PER\_LISTENER | 监听器下后端服务器数量超过配额。 | | 400 | INVALID\_HEALTH\_CHECK\_PORT\_REQUIRED | 全端口或范围端口的监听器使用TCP或HTTP健康检查时必须指定健康检查端口。 |