## 请求说明 API 名称：ModifyListenerAttributes API 描述：修改指定监听器。 ## 使用限制节流限制：每秒最多提交 5 个 API 请求。 ## 调试 ## **URI 参数** 在使用该部分 API 提交请求时必须包含以下 URI 参数。 > 除了 URI 参数，该 API 请求还需要包含签名参数。关于更多签名参数的信息，参见[公共请求参数](../6406/113575)。 |**名称** |**类型** |**是否必选** |**格式** |**说明** | |---|---|---|---|---| |Action |string |是 |[a\-zA\-Z]+ |API 名称，如 ModifyListenerAttributes 。 | |Version |string |是 |YYYY\-MM\-DD |API 版本信息。该参数的取值是 2020\-04\-01 。 | |X\-Expires |int |否 |900 |表示签名的有效时间，单位是秒，默认值是900。 | ## 请求参数在使用该 API 提交请求时，请求参数中可以包含的参数如下。 |**参数** |**类型** |**是否必选** |**参数说明** |**示例值** | |---|---|---|---|---| |ListenerId |String |是 |待修改的监听器 ID。 |lsn\-abc\*\*\*\*\*\*\* | |ListenerName |String |否 |监听器的名字。|test |\ | | | || |\ | | | |* 不能以http://或https://开头。| |\ | | | |* 必须以字母或中文开头，可包含数字、点（.）、下划线（_）和短横线（\-）。| |\ | | | |* 长度限制在1\-128字符之间。 | | |Enabled |String |否 |监听器开启/关闭，取值如下：|on |\ | | | || |\ | | | |* on：开启。| |\ | | | |* off：关闭。 | | |CertificateSource |String |否 |监听器关联的默认证书的来源，每次修改默认证书时，务必指定该参数，否则默认值为 alb ，系统将按 alb 证书处理。支持的取值如下：|cert_center |\ | | | || |\ | | | |* alb（默认）：表示通过 ALB 上传的证书。[标准版ALB实例](https://www.volcengine.com/docs/6406/1387342)不支持此取值。| |\ | | | |* cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 | | |CertificateId |String |否 |监听器关联的证书 ID。|cert\-\*\*\*\*\*\* |\ | | | |当修改 HTTPS 监听器的服务器证书且证书来源为 alb 时，需要指定该参数。 | | |CertCenterCertificateId |String |否 |监听器关联的证书ID。|cert\-\*\*\*\*\*\*\*\* |\ | | | |当修改 HTTPS 监听器的服务器证书且证书来源为 cert_center 时，需要指定该参数。 | | |CACertificateSource |String |否 |监听器关联的 CA 证书的来源。|pca_root |\ | | | |该参数仅对 HTTPS 监听器有效，用于双向认证。| |\ | | | |修改 CA 证书时，必须指定该参数，否则该参数采用默认值 alb。支持的取值如下：| |\ | | | || |\ | | | |* alb：表示通过 ALB 上传的证书。标准版 ALB 实例不支持此来源的证书。| |\ | | | |* pca_root：表示通过火山引擎证书中心购买或上传的私有根 CA 证书。| |\ | | | |* pca_sub：表示通过火山引擎证书中心购买或上传的私有子 CA 证书。 | | |CACertificateId |String |否 |监听器关联的 CA 证书的 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 alb 时，需要指定该参数。 |cert\-\*\*\*\*\*\* | |PcaRootCACertificateId |String |否 |监听器关联的 CA 证书的 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 pca_root 时，需要指定该参数。 |cert\-\*\*\*\*\*\* | |PcaSubCACertificateId |String |否 |监听器关联的 CA 证书 ID。当修改 HTTPS 监听器的 CA 证书且 CACertificateSource 的值是 pca_sub 时，需要指定该参数。 |cert\-\*\*\*\*\*\* | |ServerGroupId |String |否 |监听器关联的默认服务器组 ID 。 |rsp\-\*\*\*\*\*\* | |EnableHttp2 |String |否 |HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效，取值如下：|off |\ | | | || |\ | | | |* on：开启。| |\ | | | |* off：关闭。 | | |EnableQuic |String |否 |QUIC 特性开关，该参数仅对 HTTPS 监听器有效，取值如下：|off |\ | | | || |\ | | | |* on：开启。| |\ | | | |* off：关闭。| |\ | | | | 只有标准版 ALB 实例支持 QUIC。如需使用 QUIC 功能，请联系您的客户经理。 | | |CustomizedCfgId |String |否 |绑定个性化配置。|ccfg\-\*\*\*\*\* |\ | | | || |\ | | | |* 只能绑定 Active 状态的个性化配置。| |\ | | | |* 要删除个性化配置时设置该字段为空字符串。不传该参数时不做修改。 | | |AclStatus |String |否 |* 是否开启访问控制功能。取值如下：|off |\ | | | | * on：开启。| |\ | | | | * off ：不开启。| |\ | | | |* 不填表示不修改访问控制相关信息。| |\ | | | |* 配置本参数后会清空已配置的AclType和AclIds参数。| |\ | | | |* 如果将本参数值从 on 修改为 off，将清空AclType和AclIds参数中的值。| |\ | | | |* 如果将本参数值从 off 修改为 on，则必须同时设置AclType和AclIds参数的值。 | | |AclType |String |否 |访问控制的方式。取值如下:|black |\ | | | || |\ | | | |* white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器不会转发任何请求。| |\ | | | |* black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器会转发全部请求。| |\ | | | | 当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。 | | |AclIds.N |List of String |否 |监听器绑定的访问控制策略组ID。|AclIds.1=acl\-3cj44nv0jhhxc6c6rrtet\*\*\*\*& AclIds.2=acl\-2febxt4pu0zy85oxruw0t\*\*\*\* |\ | | | || |\ | | | |* \- N：表示访问控制策略组的序号，数量上限为5个。| |\ | | | |* 多个访问控制策略组ID间使用“&”分隔。| |\ | | | | 当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。 | | |Description |String |否 |监听器的描述信息。|test |\ | | | || |\ | | | |* 不能以http://或https://开头。| |\ | | | |* 必须以字母或中文开头，可包含数字、英文逗号（,）、点号（.）、下划线（_）、空格（）、等号（=）、短横线（\-）、中文逗号（，）、中文句号（。）。| |\ | | | |* 长度限制为1 ～ 255个字符。 | | |DomainExtensions |\- |否 |HTTPS监听器关联的扩展域名列表，具体请参见下表 [DomainExtensions](https://www.volcengine.com/docs/6406/113683?lang=zh#NmfLwBLH) 。 |\- | |AccessLogRecordCustomizedHeadersEnabled |String |否 |是否为该监听器开启“在访问日志中记录自定义header”的功能，取值如下：|on |\ | | | || |\ | | | |* on：开启。| |\ | | | |* off：关闭。 | | #### **DomainExtensions** |**参数** |**类型** |**是否必选** |**参数说明** |**示例值** | |---|---|---|---|---| |DomainExtensions.N.DomainExtensionId |List of Struct |否 |扩展域名ID，仅删除和修改时需要指定。 |DomainExtensions.1.DomainExtensionId=dc\-qwertasdf&DomainExtensions.2.DomainExtensionId=dc\-poiuylkjhg |\ | | | || |\ | | | |* \- N：表示域名的序号。| |\ | | | |* 一个HTTPS监听器能关联的扩展域名上限为20个。 | | |DomainExtensions.N.Domain |List of Struct |否 |域名。|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监听器下的域名不能重复。| |\ | | | | * 匹配域名时，对域名的大小写不敏感。 | | |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.CertificateId |String |否 |* 域名使用的服务器证书。当修改扩展证书且证书来源为 alb 时，需要指定该参数。|DomainExtensions.1.CertificateId=cert\-qwertyuqwert&DomainExtensions.2.CertificateId=cert\-zxcvbgasdfn |\ | | | |* \- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个。 | | |DomainExtensions.N.CertCenterCertificateId |String |否 |* 域名使用的服务器证书。修改扩展证书且证书来源为 cert_center 时，需要指定该参数。|DomainExtensions.1.CertCenterCertificateId=cert\-qwertyuqwert&DomainExtensions.2.CertCenterCertificateId=cert\-zxcvbgasdfn |\ | | | |* \- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 | | |DomainExtensions.N.Action |List of Struct |否 |对指定扩展域名的操作，\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个。支持：|DomainExtensions.1.Action=add&DomainExtensions.2.Action=modify |\ | | | || |\ | | | |* create（新增）。| |\ | | | |* modify（修改）。| |\ | | | |* delete（删除）。 | | ## 返回参数 |**参数** |**类型** |**参数说明** |**示例值** | |---|---|---|---| |RequestId |String |请求 ID 。 |20210811152539010225146063030\*\*\*\* | ## 示例 ### 请求示例 ```http GET /?Action=ModifyListenerAttributes&ListenerId=lsn-2fek3rgsxhrsw5oxruwec****&Version=2020-04-01&ListenerName=test&Enabled=off HTTP/1.1 Host: alb.cn-beijing.volcengineapi.com Region: cn-beijing ServiceName: alb ``` ### 返回示例 ```json { "ResponseMetadata": { "RequestId": "20210816110638****2514606306AF947C", "Action": "ModifyListenerAttributes", "Version": "2020-04-01", "Service": "alb", "Region": "cn-beijing" }, "Result": { "RequestId": "202108161106****22514606306AF947C", } } ``` ## 错误码如果响应正文包含 Error 字段，则表示 API 请求失败。此处仅展示当前 API 的错误码，更多错误码请参见[公共错误码](../6406/113579)。 |HTTP Code |错误码 |错误信息 |错误描述 | |---|---|---|---| |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CertificateId。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CertCenterCertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CertCenterCertificateId。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'DomainExtensions.CertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: DomainExtensions.CertificateId。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'DomainExtensions.CertCenterCertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: DomainExtensions.CertCenterCertificateId。 | |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 |InvalidServerGroup.InvalidStatus |The specified ServerGroup is not in the correct status for the request. |指定的服务器组所处状态无法响应该请求。 | |400 |InvalidVpcForServerGroup.LoadBalancerMismatch |The specified VPC of ServerGroup and LoadBalancer do not match. |指定的服务器组和 ALB 实例的 VPC 不匹配。 | |400 |InvalidCertificateType.FunctionMismatch |The specified Certificate's type and Function do not match. |指定的证书的类型与预期功能不匹配。 | |400 |InvalidServerCertificate.InvalidStatus |The specified Server Certificate is not in the correct status for the request. |指定的服务器证书所处状态无法响应该请求。 | |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 |InvalidCACertificate.InvalidStatus |The specified CA Certificate is not in the correct status for the request. |指定的 CA 证书所处状态无法响应该请求。 | |400 |InvalidEnableHttp2.Malformed |The specified EnableHttp2 is malformed. |指定的 EnableHttp2 参数格式不合法。 | |400 |InvalidEnableQuic.Malformed |The specified EnableQuic is malformed. |指定的 EnableQuic 参数格式不合法。 | |400 |InvalidCertificateSource.Malformed |The specified CertificateSource is malformed. |指定的 CertificateSource 参数格式不合法。 | |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 |InvalidIndexOrder.Malformed |The specified index order is malformed. |指定的索引顺序参数格式不合法。 | |400 |InvalidDomainExtensions.Domain.Malformed |The specified DomainExtensions.Domain is malformed. |指定的 DomainExtensions.Domain 参数格式不合法。 | |400 |InvalidDomainExtensions.Domain.Duplicated |The specified DomainExtensions.Domain is duplicated. Domain Extensions in one listener can not be same. |指定的 DomainExtensions.Domain 重复。一个监听器下关联的扩展域名不能重复。 | |400 |InvalidDomainExtensions.CertificateSource.Malformed |The specified DomainExtensions.CertificateSource is malformed. |指定的 DomainExtensions.CertificateSource 参数格式不合法。 | |400 |InvalidDomainExtensions.Certificate.InvalidStatus |The specified DomainExtension Certificate is not in the correct status for the request. |指定的扩展域名证书所处状态无法响应该请求。 | |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.Action.Malformed |The specified DomainExtensions.Action is malformed. |指定的 DomainExtensions.Action 参数格式不合法。 | |400 |InvalidAclStatus.Malformed |The specified AclStatus is malformed. |指定的 AclStatus 参数格式不合法。 | |400 |InvalidAclType.Malformed |The specified AclType is malformed. |指定的 AclType 参数格式不合法。 | |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 |InvalidAclId.Duplicated |The specified AclId is duplicated. |指定的 AclId 重复。 | |400 |InvalidCustomizedCfg.InvalidStatus |The specified CustomizedCfg is not in the correct status for the request. |指定的个性化配置所处状态无法响应该请求。 | |400 |InvalidLoadBalancer.InvalidStatus |The specified LoadBalancer is not in the correct status for the request. |指定的 ALB 实例所处状态无法响应该请求。 | |400 |InvalidEnabled.Malformed |The specified Enabled is malformed. |指定的 Enabled 参数格式不合法。 | |400 |OperationFailed.OperateGtmFailed |The request on the specified resource failed due to operating gtm failed. |因操作 GTM 实例失败，对于该资源的操作请求失败。 | |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 |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 |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.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.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.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.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 |LimitExceed.DomainExtension |You've reached the limit on the number of domain extensions that you can operate at a time. |已达到单次可操作的扩展域名的数量上限。 | |400 |InvalidCertificateId.Duplicated |The specified CertificateId is duplicated. Certificates in one listener can not be same. |指定的 CertificateId 重复。一个监听器下的证书不能重复。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'PcaLeafCertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: PcaLeafCertificateId。 | |400 |GMSingleCertExclusive |The request on the specified Resource is denied due to the GM single certificate requiring exclusive deployment. |因国密单证书不能与其他类型证书同时部署，对于该资源的操作请求被拒绝。 | |400 |InvalidCACertificateSource.Malformed |The specified CACertificateSource is malformed. |指定的 CACertificateSource 参数格式不合法。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CACertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CACertificateId。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'PcaRootCACertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: PcaRootCACertificateId。 | |400 |MissingParameter |The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'PcaSubCACertificateId'. |该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: PcaSubCACertificateId。 | |400 |InvalidCACertificateId.OriginalCertificateSourceMismatch |The specified CACertificateId and original CertificateSource do not match. |指定的 CA 证书字段与原始 CA 证书类型不匹配。 | |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. |指定的个性化配置不存在。 |

负载均衡