调用 ModifyListenerAttributes 接口，修改指定监听器。 ## 使用说明 * 每秒最多提交 5 个 API 请求。 * 以下可选参数如不配置，则保持原有配置。 ## 调试 ## 请求参数下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6369/67268)。 **Action** string %%require%% `示例值：ModifyListenerAttributes` 要执行的操作，取值：ModifyListenerAttributes。 **Version** string %%require%% `示例值：2020-04-01` API的版本，取值：2020\-04\-01。 **AccessLogRecordCustomizedHeadersEnabled** string `可选` `示例值：on` 是否为该监听器开启“在访问日志中记录自定义header”的功能，取值如下： * on：开启。 * off：关闭。 **XRealIpEnabled** string `可选` `示例值：on` 监听器开启/禁用X\-real\-ip Header。取值如下： * on（默认值）：开启。 * off：关闭。 **ListenerName** string `可选` `示例值：test` 监听器的名字。 * 不能以http://或https://开头。 * 必须以字母或中文开头，可包含数字、点（.）、下划线（_）和短横线（\-）。 * 长度限制在1\-128字符之间。 **Enabled** string `可选` `示例值：on` 监听器开启/关闭，取值如下： * on：开启。 * off：关闭。 **CertificateSource** string `可选` `示例值：cert_center` 默认证书的来源。取值如下： * alb：表示通过 ALB 上传的证书。[标准版ALB实例](https://www.volcengine.com/docs/6406/1387342)不支持此取值。 * cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 :::tip 每次修改默认证书时，务必指定该参数，否则默认值为 alb ，系统将按 alb 证书处理. ::: **CACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书的 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 alb 时，需要指定该参数。 **CertCenterCertificateId** string `可选` `示例值：cert-********` 证书中心的证书ID。当修改 HTTPS 监听器的服务器证书且证书来源为 cert_center 时，需要指定该参数。 **EnableHttp2** string `可选` `示例值：off` HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效，取值如下： * on：开启。 * off：关闭。 **EnableQuic** string `可选` `示例值：off` QUIC 特性开关，该参数仅对 HTTPS 监听器有效，取值如下： * on：开启。 * off：关闭。只有标准版 ALB 实例支持 QUIC。如需使用 QUIC 功能，请联系您的客户经理。 **CustomizedCfgId** string `可选` `示例值：ccfg-*****` 绑定个性化配置。 * 只能绑定 Active 状态的个性化配置。 * 要删除个性化配置时设置该字段为空字符串。不传该参数时不做修改。 **AclStatus** string `可选` `示例值：off` 是否开启访问控制功能。 * 取值如下： * on：开启。 * off ：不开启。 * 不填表示不修改访问控制相关信息。 * 配置本参数后会清空已配置的AclType和AclIds参数。 * 如果将本参数值从 on 修改为 off，将清空AclType和AclIds参数中的值。 * 如果将本参数值从 off 修改为 on，则必须同时设置AclType和AclIds参数的值。 **PcaLeafCertificateId** string `可选` `示例值：cert-********` 监听器关联的证书ID。当修改 HTTPS 监听器的服务器证书且证书来源为 pca_leaf 时，需要指定该参数。 **AclType** string `可选` `示例值：black` 访问控制的方式。取值如下: * white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器不会转发任何请求。 * black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器会转发全部请求。当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。 **CACertificateSource** string `可选` `示例值：pca_root` 监听器关联的 CA 证书的来源。该参数仅对 HTTPS 监听器有效，用于双向认证。修改 CA 证书时，必须指定该参数，否则该参数采用默认值 alb。支持的取值如下： * alb：表示通过 ALB 上传的证书。标准版 ALB 实例不支持此来源的证书。 * pca_root：表示通过火山引擎证书中心购买或上传的私有根 CA 证书。 * pca_sub：表示通过火山引擎证书中心购买或上传的私有子 CA 证书。 **Description** string `可选` `示例值：test` 监听器的描述信息。 * 不能以http://或https://开头。 * 必须以字母或中文开头，可包含数字、英文逗号（,）、点号（.）、下划线（_）、空格（）、等号（=）、短横线（\-）、中文逗号（，）、中文句号（。）。 * 长度限制为1 ～ 255个字符。 **DomainExtensions.N.DomainExtensionId** string[] `可选` `示例值：DomainExtensions.1.DomainExtensionId=dc-qwertasdf&DomainExtensions.2.DomainExtensionId=dc-poiuylkjhg` 扩展域名ID，仅删除和修改时需要指定。 * 参数\- N：表示域名的序号。 * 一个HTTPS监听器能关联的扩展域名上限为20个。 **PcaRootCACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书的 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 pca_root 时，需要指定该参数。 **DomainExtensions.N.Domain** string[] `可选` `示例值：DomainExtensions.1.Domain=abc.com&DomainExtensions.2.Domain=def.com` 域名。 * 参数 \- N：表示域名的序号。 * 一个HTTPS监听器能关联的扩展域名上限为20个。 * 格式规范具体如下： * 通常不能为空。但是如果实例支持自动选择扩展证书，即`SniAutoMatch`为`on`，则`DomainExtensions.N.Domain`需传入空字符串。 * 需至少包含一个‘.’，且不允许以‘.’开头或结尾。 * 仅允许包含小写字母、数字、‘.’、‘\-‘、‘\*’。 * 长度限制为1 ～ 128个字符。 * 泛域名：使用“\*”代替1个或多个字符。 * “\*”必须在域名开头或结尾。 * 同一条域名中“\*”不能出现两次。 * “\*”前后不能有除了.以外的字符。 * 合法示例： *.com、www.test.* 。 * 非法示例：*aaa.com、www.* .com * 精确域名：符合域名规范的精确域名，例如：www.test.com。 * 同一HTTPS监听器下的域名不能重复。 * 匹配域名时，对域名的大小写不敏感。 **PcaSubCACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 pca_sub 时，需要指定该参数。 **DomainExtensions.N.Action** string[] `可选` `示例值：DomainExtensions.1.Action=add&DomainExtensions.2.Action=modify` 对指定扩展域名的操作。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个。 * 取值如下： * create：新增。 * modify：修改。 * delete：删除。 **DomainExtensions.N.CertificateSource** string[] `可选` `示例值：DomainExtensions.1.CertificateSource=cert_center&DomainExtensions.2.CertificateSource=alb` 域名使用的服务器证书来源。 * 取值如下： * alb：表示通过 ALB 上传的证书。[标准版ALB实例](https://www.volcengine.com/docs/6406/1387342)不支持此取值。 * cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 * 每次修改默认证书时，务必指定该参数，否则默认值为 alb ，系统将按 alb 证书处理。 **DomainExtensions.N.CertCenterCertificateId** string[] `可选` `示例值：DomainExtensions.1.CertCenterCertificateId=cert-qwertyuqwert&DomainExtensions.2.CertCenterCertificateId=cert-zxcvbgasdfn` 域名使用的服务器证书。 * 修改扩展证书且证书来源为 cert_center 时，需要指定该参数。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 **ListenerId** string %%require%% `示例值：lsn-abc*******` 待修改的监听器 ID。 **ServerGroupId** string `可选` `示例值：rsp-******` 监听器关联的默认服务器组 ID。 **AclIds.N** string[] `可选` `示例值：AclIds.1=acl-3cj44nv0jhhxc6c6rrtet****& AclIds.2=acl-2febxt4pu0zy85oxruw0t****` 监听器绑定的访问控制策略组ID。 * 参数\- N：表示访问控制策略组的序号，数量上限为5个。 * 多个访问控制策略组ID间使用“&”分隔。 * 当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。 **DomainExtensions.N.CertificateId** string[] `可选` `示例值：DomainExtensions.1.CertificateId=cert-qwertyuqwert&DomainExtensions.2.CertificateId=cert-zxcvbgasdfn` 域名使用的服务器证书。 * 当修改扩展证书且证书来源为 alb 时，需要指定该参数。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个。 **CertificateId** string `可选` `示例值：cert-******` ALB侧证书管理的证书 ID。当修改 HTTPS 监听器的服务器证书且证书来源为 alb 时，需要指定该参数。 **DomainExtensions.N.PcaLeafCertificateId** string[] `可选` `示例值：DomainExtensions.1.PcaLeafCertificateId=pca_leaf-qwertyuqwert&DomainExtensions.2.PcaLeafCertificateId=pca_leaf-zxcvbgasdfn` 域名使用的服务器证书。 * 当证书来源为 pca_leaf 时有效。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 ## 返回参数下方仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6369/80336)。 **RequestId** string `示例值：20210811152539010225146063030****` 请求 ID 。 ## 请求示例 ```text GET /?Action=ModifyListenerAttributes&ListenerId=lsn-2fek3rgsxhrsw5oxruwec****&Version=2020-04-01&ListenerName=test&Enabled=off HTTP/1.1 Host: alb.cn-beijing.volcengineapi.com X-Date: 20251121T094038Z Authorization: HMAC-SHA256 Credential=Adfks******wekfwe/20251121/cn-beijing/alb/request, SignedHeaders=host;x-date, Signature=47a7d934ff7b37c03938******cd7b8278a40a1057690c401e92246a0e41085f ``` ## 返回示例 ```text { "ResponseMetadata": { "RequestId": "20210816110638****2514606306AF947C", "Action": "ModifyListenerAttributes", "Version": "2020-04-01", "Service": "alb", "Region": "cn-beijing" }, "Result": { "RequestId": "202108161106****22514606306AF947C" } } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6369/68677)文档。 |状态码 |错误码 |错误信息 |说明 | |---|---|---|---| |400 |Invalid%s.Malformed |MismatchThe specified %s is malformed. |指定的 %s 参数格式不合法。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, '%s'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: %s。 | |400 |InvalidParameter |Data unmarshal failed. |请求解析失败。 | |400 |OperationDenied.AccountArrears |The request on the specified resource is denied due to the account being in arrears status. |因账号处于欠费状态，对于该资源的操作请求被拒绝。 | |400 |InvalidListenerName.Malformed |The specified ListenerName is malformed. |指定的 ListenerName 参数格式不合法。 | |400 |InvalidDescription.Malformed |The specified Description is malformed. |指定的 Description 参数格式不合法。 | |400 |InvalidAclStatus.Malformed |The specified AclStatus is malformed. |指定的 AclStatus 参数格式不合法。 | |400 |InvalidDomainExtensions.Action.Malformed |The specified DomainExtensions.Action is malformed. |指定的 DomainExtensions.Action 参数格式不合法。 | |400 |InvalidDomainExtensions.DomainExtensionId.Duplicated |The specified DomainExtensions.DomainExtensionId is duplicated. Only one type domain extension action is supported on one domain extension in one request. |指定的 DomainExtensions.DomainExtensionId 重复。一次请求中指定的扩展域名仅支持一种操作。 | |400 |InvalidDomainExtensions.Certificate.InvalidStatus |The specified DomainExtension Certificate is not in the correct status for the request. |指定的扩展域名证书所处状态无法响应该请求。 | |400 |InvalidDomainExtensions.Domain.Duplicated |The specified DomainExtensions.Domain is duplicated. Domain Extensions in one listener can not be same. |指定的 DomainExtensions.Domain 重复。一个监听器下关联的扩展域名不能重复。 | |400 |InvalidDomainExtensions.Domain.Malformed |The specified DomainExtensions.Domain is malformed. |指定的 DomainExtensions.Domain 参数格式不合法。 | |400 |InvalidIndexOrder.Malformed |The specified index order is malformed. |指定的索引顺序参数格式不合法。 | |400 |OperationDenied.DualStackEnableQuicUnsupported |The request on the specified Listener is denied due to the dual stack load balancer listener not support to enable quic. |因双栈 ALB 实例暂时不支持监听器开启 Quic，对于该监听器的操作请求被拒绝。 | |400 |InvalidEnableHttp2.Malformed |The specified EnableHttp2 is malformed. |指定的 EnableHttp2 参数格式不合法。 | |400 |InvalidCACertificate.InvalidStatus |The specified CA Certificate is not in the correct status for the request. |指定的 CA 证书所处状态无法响应该请求。 | |400 |InvalidServerCertificate.InvalidStatus |The specified Server Certificate is not in the correct status for the request. |指定的服务器证书所处状态无法响应该请求。 | |400 |InvalidCertificateType.FunctionMismatch |The specified Certificate's type and Function do not match. |指定的证书的类型与预期功能不匹配。 | |400 |InvalidVpcForServerGroup.LoadBalancerMismatch |The specified VPC of ServerGroup and LoadBalancer do not match. |指定的服务器组和 ALB 实例的 VPC 不匹配。 | |400 |InvalidServerGroup.InvalidStatus |The specified ServerGroup is not in the correct status for the request. |指定的服务器组所处状态无法响应该请求。 | |400 |InvalidEnableQuic.Malformed |The specified EnableQuic is malformed. |指定的 EnableQuic 参数格式不合法。 | |400 |QuotaExceed.RulePerGroup |You've reached the limit on the number of rules per server group you can associate with, resource xxx, usage xx/xx. |已达到每个服务器组可关联转发规则的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |QuotaExceed.ListenerPerAcl |You've reached the limit on the number of listeners per ACL you can associate with, resource xxx, usage xx/xx. |已达到每个 ACL 可关联的监听器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |QuotaExceed.AclPerListener |You've reached the limit on the number of ACLs per listener you can associate with, resource xxx, usage xx/xx. |已达到每个监听器可关联的 ACL 的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |QuotaExceed.ListenerPerCustomizedCfg |You've reached the limit on the number of listeners per CustomizedCfg you can associate with, resource xxx, usage xx/xx. |已达到每个个性化配置可关联的监听器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |QuotaExceed.SniDomainPerListener |You've reached the limit on the number of sni domains per listener you can associate with, resource xxx, usage xx/xx. |已达到每个监听器可关联的 sni 域名的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |QuotaExceed.ServerPerInstance |You've reached the limit on the number of backend servers per ALB you can associate with, resource xxx, usage xx/xx. |已达到每个实例可关联的后端服务器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。 | |400 |OperationFailed.OperateGtmFailed |The request on the specified resource failed due to operating gtm failed. |因操作 GTM 实例失败，对于该资源的操作请求失败。 | |400 |InvalidEnabled.Malformed |The specified Enabled is malformed. |指定的 Enabled 参数格式不合法。 | |400 |InvalidCustomizedCfg.InvalidStatus |The specified CustomizedCfg is not in the correct status for the request. |指定的个性化配置所处状态无法响应该请求。 | |400 |InvalidAclId.Duplicated |The specified AclId is duplicated. |指定的 AclId 重复。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'AclIds'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: AclIds。 | |400 |InvalidAclType.Malformed |The specified AclType is malformed. |指定的 AclType 参数格式不合法。 | |400 |InvalidCertificateSource.Malformed |The specified CertificateSource is malformed. |指定的 CertificateSource 参数格式不合法。 | |400 |InvalidCertificateServiceSSLCertificate.InvalidStatus |The specified Certificate Service SSL Certificate is not in the correct status for the request. Please check if the certificate has been issued. |指定的证书中心 SSL 证书所处状态无法响应该请求。请确认证书处于已签发状态。 | |400 |OperationFailed.QueryIAM |The request on the specified resource failed due to the query on IAM failed. |因请求 IAM 失败，对于该资源的操作请求失败。 | |400 |OperationFailed.QueryCertificateService |The request on the specified resource failed due to the query on Certificate Service failed. |因请求证书中心服务失败，对于该资源的操作请求失败。 | |400 |InvalidDomainExtensions.CertificateSource.Malformed |The specified DomainExtensions.CertificateSource is malformed. |指定的 DomainExtensions.CertificateSource 参数格式不合法。 | |400 |LimitExceed.DomainExtension |You've reached the limit on the number of domain extensions that you can operate at a time. |已达到单次可操作的扩展域名的数量上限。 | |400 |InvalidProxyProtocolDisabled.Malformed |The specified ProxyProtocolDisabled is malformed. |指定的 ProxyProtocolDisabled 参数格式不合法。 | |400 |InvalidCertificateId.Duplicated |The specified CertificateId is duplicated. Certificates in one listener can not be same. |指定的 CertificateId 重复。一个监听器下的证书不能重复。 | |400 |InvalidLoadBalancer.InvalidStatus |The specified LoadBalancer is not in the correct status for the request. |指定的 ALB 实例所处状态无法响应该请求。 | |400 |InvalidALRCHEnabled.Malformed |The specified AccessLogRecordCustomizedHeadersEnabled is malformed |指定的AccessLogRecordCustomizedHeadersEnabled参数格式不合法 | |400 |InvalidXRealIpEnabled.Malformed |The specified XRealIpEnabled is malformed. |指定的 XRealIpEnabled 参数格式不合法。 | |403 |Forbidden |You are not authorized to disable X\-real\-ip header. |您无权限禁用 X\-real\-ip header。 | |404 |InvalidListener.NotFound |The specified Listener does not exist. |指定的监听器不存在。 | |404 |InvalidLoadBalancer.NotFound |The specified LoadBalancer does not exist. |指定的 ALB 实例不存在。 | |404 |InvalidServerGroup.NotFound |The specified ServerGroup does not exist. |指定的服务器组不存在。 | |404 |InvalidServerCertificate.NotFound |The specified Server Certificate does not exist. |指定的服务器证书不存在。 | |404 |InvalidCACertificate.NotFound |The specified CA Certificate does not exist. |指定的 CA 证书不存在。 | |404 |InvalidDomainExtensions.Certificate.NotFound |The specified DomainExtension Certificate does not exist. |指定的扩展域名证书不存在。 | |404 |InvalidDomainExtension.NotFound |The specified Domain Extension does not exist. |指定的扩展域名不存在。 | |404 |InvalidAcl.NotFound |The specified ACL does not exist. |指定的 ACL 不存在。 | |404 |InvalidCustomizedCfg.NotFound |The specified CustomizedCfg does not exist. |指定的个性化配置不存在。 | |500 |InternalError |An internal error has occurred. |发生内部错误。请稍后重试或联系工程师进一步咨询。 |