> 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/modifylistener.md).
# ModifyListener
## 1. 接口描述
本接口(ModifyListener)用于修改负载均衡监听器的属性，包括监听器的名称、健康检查参数、转发方式等。
{% hint style="info" %}
**注意事项**
* 不支持修改监听器的监听协议。
* `algoOpts`（无状态转发）与`persistent`（会话保持）之所以互斥，是因为无状态转发逐包哈希转发、不维护连接跟踪表，无法保证同一客户端命中同一后端。
* `algoOpts`的关闭状态在查询侧不会表现为`None`： [DescribeListeners](/api-reference/cn/zlb/load-balancer-listener/describelisteners.md) 等查询接口不返回`None`，未开启一律表现为该字段为空。
{% endhint %}
## 2. 请求参数
以下请求参数列表仅列出了接口中需要的请求参数
| 参数名称 | 必选 | 类型 | 描述 |
| -------------- | -- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| loadBalancerId | 是 | String | 负载均衡器ID。
可通过调用 DescribeLoadBalancers 获取。
|
| listenerId | 是 | String | 负载均衡器的监听器ID。
可通过调用 DescribeListeners 获取。
|
| listenerName | 否 | String | 负载均衡器的监听器名称。
不传则不会进行修改。
|
| healthCheck | 否 | [HealthCheck](/api-reference/cn/zlb/datastructure.md#healthcheck) | 负载均衡器的监听器健康检查。
不传则不会修改，如果开启或关闭，请设置HealthCheck.enabled字段。
|
| scheduler | 否 | [ListenerScheduler](/api-reference/cn/zlb/datastructure.md#listenerscheduler) | 监听器的调度算法。
不传则不会进行修改。
|
| port | 否 | String | 监听器端口。
多个端口使用半角逗号（,）分隔。
当端口是范围时用-连接，例如：10000-10005。
端口的取值范围为0～65535，0代表全范围端口。
不指定将不会进行修改。
范围端口与全端口在配额计算中均按1个端口计。
连续的单端口会被自动合并为区间端口后再保存和返回，例如1,2,3,4,5会被保存为1-5。
|
| kind | 否 | [LoadBalancerKind](/api-reference/cn/zlb/datastructure.md#loadbalancerkind) | 工作模式。
修改为DR模式后，后端服务器上已指定的端口将失效，一律跟随监听器端口。
修改后必须与该负载均衡器下其他监听器的工作模式保持一致。
DR模式下监听器不支持设置为全端口（0）；监听器当前端口已是全端口（0）时，也不允许修改为DR。
负载均衡实例的ipStackType为IPv6时只支持DR。
|
| persistent | 否 | Integer | 会话保持时间，单位秒。
与algoOpts（调度算法高级选项）互斥：若该监听器已开启algoOpts，不可修改为非0值，需一并传algoOpts=None将其清空。
可选值范围：\[0, +)
|
| idleTimeout | 否 | Integer | 空闲超时时间，单位秒。
可选值范围：\[60, +)
|
| algoOpts | 否 | [ListenerAlgoOpts](/api-reference/cn/zlb/datastructure.md#listeneralgoopts) | 调度算法高级选项。
仅当工作模式（kind）为DR且调度算法（scheduler）为mh时可设置。
不传表示不修改该字段；传None表示显式清空已开启的选项。
校验按修改后生效的最终状态判定：若该监听器已开启此选项，把kind或scheduler改为其它组合时也需一并传None。
开启后与会话保持（persistent）互斥：若该监听器已开启此选项，把persistent改为非0值同样会报错，需一并传None将其清空。
|
## 3. 响应结果
| 参数名称 | 类型 | 描述 |
| --------- | ------ | -------------------------------------------------------- |
| requestId | String | 唯一请求 ID。
每次请求都会返回。定位问题时需要提供该次请求的 requestId。
|
## 4. 代码示例
{% tabs %}
{% tab title="示例" %}
**1. 修改负载均衡监听器的名称、健康检查参数以及转发策略。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request：
{
"loadBalancerId" : "",
"listenerId" : "",
"listenerName" : "sampleName",
"persistent": 60,
"idleTimeout": 60,
"healthCheck" : {
"enabled": true,
"checkType": "PING_CHECK",
"checkPort": null,
"checkDelayLoop": 4,
"checkConnTimeout": 3,
"checkRetry": 4,
"checkDelayTry": 5,
"checkHttpGetUrl": "/",
"checkHttpStatusCode": null
},
"scheduler" : "mh"
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
**2. 开启无状态转发。`algoOpts`仅在工作模式`kind`为`DR`且调度算法`scheduler`为`mh`时可设置，且与会话保持`persistent`互斥，需同时把`persistent`置为0。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request：
{
"loadBalancerId" : "",
"listenerId" : "",
"kind": "DR",
"scheduler" : "mh",
"algoOpts": "StatelessForwarding",
"persistent": 0
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
**3. 关闭无状态转发并恢复会话保持。传`algoOpts`为`None`表示清空已开启的高级选项。**
```json
POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ModifyListener
Request：
{
"loadBalancerId" : "",
"listenerId" : "",
"algoOpts": "None",
"persistent": 60
}
Response：
{
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
"response": {
"requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
}
}
```
{% 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 | 调度算法高级选项（无状态转发）与会话保持不能同时开启。 |
| 404 | INVALID\_LB\_LISTENER\_NOT\_FOUND | 监听器不存在。 |
| 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\_PORT\_FORMAT\_ERROR | 端口格式不合法。 |
| 400 | INVALID\_PORT\_RANGE | 端口范围超出临界值。 |
| 400 | INVALID\_HEALTH\_CHECK\_PORT\_REQUIRED | 全端口或范围端口的监听器使用TCP或HTTP健康检查时必须指定健康检查端口。 |