调用 CreateListener 接口，创建监听器。 ## 使用说明每秒最多提交 5 个 API 请求。 ## 调试 ## 请求参数下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6369/67268)。 **Action** string %%require%% `示例值：CreateListener` 要执行的操作，取值：CreateListener。 **Version** string %%require%% `示例值：2020-04-01` API的版本，取值：2020\-04\-01。 **XRealIpEnabled** string `可选` `示例值：on` 监听器开启/禁用X\-real\-ip Header。取值如下： \* on（默认值）：开启。 \* off：关闭。 **ListenerName** string `可选` `示例值：test` 监听器的名字。 * 不填默认以“协议\-端口”格式命名。 * 不能以http://或https://开头。 * 必须以字母或中文开头，可包含数字、点（.）、下划线（_）和短横线（\-）。 * 长度限制在1\-128字符之间。 **Protocol** string %%require%% `示例值：HTTP` 监听器的协议。取值如下： * HTTP * HTTPS **Port** integer %%require%% `示例值：80` 监听器的监听端口，取值范围为：1 \- 65535 。 **Enabled** string `可选` `示例值：on` 开启/关闭监听器，取值如下： * on（默认值）：开启。 * off：关闭。 **CertificateSource** string `可选` `示例值：cert_center` 默认证书的来源。该参数仅对 HTTPS 监听器有效，取值如下： * alb：表示通过 ALB 上传的证书。[标准版ALB实例](https://www.volcengine.com/docs/6406/1387342)不支持此取值。 * cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 **CACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书的 ID。该参数用于 HTTPS 监听器的双向认证。 CACertificateSource 的值为 alb 时，必须指定 CACertificateId 参数。 **CertCenterCertificateId** string `可选` `示例值：cert-********` 监听器关联的证书ID，创建 HTTPS 监听器且证书来源为 cert_center 时必传。 **EnableHttp2** string `可选` `示例值：off` HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效，取值如下： * on：开启。 * off（默认值）：关闭。 **Tags.N.Value** string[] `可选` `示例值：Tags.1.Value=v1&Tags.2.Value=v2` 用户标签的标签值。 * 如果传入该参数，则必须先传入Tags.N.Key。 * 具体规则如下： * 长度限制为0～256个字符。 * 大小写敏感。 * 不能以空格开头或结尾。 * 允许包含各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、减号（\-）和@。 **EnableQuic** string `可选` `示例值：off` QUIC 特性开关，该参数仅对 HTTPS 监听器有效，取值如下： * on：开启。 * off（默认值）：关闭。只有标准版 ALB 实例支持 QUIC。如需使用 QUIC 功能，请联系您的客户经理。 **Tags.N.Key** string[] `可选` `示例值：Tags.1.Key=k1&Tags.2.Key=k2` 用户标签的标签键。具体规则如下： * 长度限制为1～128个字符。 * 大小写敏感。 * 不能以volc:的任意大小写组合开头。 * 不能以空格开头或结尾。 * 允许包含各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、减号（\-）和@。 * 同一资源的标签键不允许重复。 **AclStatus** string `可选` `示例值：off` 是否开启访问控制功能。取值如下： * on：开启。 * off（默认值）：不开启。 **PcaLeafCertificateId** string `可选` `示例值：cert-********` 监听器关联的证书ID，创建 HTTPS 监听器且证书来源为 pca_leaf 时必传。 **AclType** string `可选` `示例值：black` 访问控制的方式。取值如下: * white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器不会转发任何请求。 * black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器会转发全部请求。当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。 **Description** string `可选` `示例值：test` 监听器的描述信息。 * 不能以http://或https://开头。 * 必须以字母或中文开头，可包含数字、英文逗号（,）、点号（.）、下划线（_）、空格（）、等号（=）、短横线（\-）、中文逗号（，）、中文句号（。）。 * 长度限制为1 ～ 255个字符。 * 不填默认为空字符串。 **CACertificateSource** string `可选` `示例值：pca_root` 监听器关联的 CA 证书的来源。该参数仅对 HTTPS 监听器有效，用于双向认证。取值如下： * alb（默认）：表示通过 ALB 上传的证书。标准版 ALB 实例不支持此来源的证书。 * pca_root：表示通过火山引擎证书中心购买或上传的私有根 CA 证书。 * pca_sub：表示通过火山引擎证书中心购买或上传的私有子 CA 证书。 :::tip 如需为 HTTPS 监听器开启双向认证，您需要同时指定 CA 证书来源和 CA 证书 ID。 * CACertificateSource 的值为 alb 时，须指定 CACertificateId 参数。 * CACertificateSource 的值为 pca_root 时，须指定 PcaRootCACertificateId 参数。 * CACertificateSource 的值为 pca_sub 时，须指定 PcaSubCACertificateId 参数。 ::: **DomainExtensions.N.Domain** string[] `可选` `示例值：DomainExtensions.1.Domain=abc.com&DomainExtensions.2.Domain=def.com` 域名。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～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。 **PcaRootCACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书的 ID。该参数用于 HTTPS 监听器的双向认证。 CACertificateSource 的值为 pca_root 时，必须指定 PcaRootCACertificateId 参数。 **DomainExtensions.N.CertCenterCertificateId** string[] `可选` `示例值：DomainExtensions.1.CertCenterCertificateId=cert-qwertyuqwert&DomainExtensions.2.CertCenterCertificateId=cert-zxcvbgasdfn` 域名使用的服务器证书。 * 当证书来源为 cert_center 时有效。 * 参数\- N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 **PcaSubCACertificateId** string `可选` `示例值：cert-******` 监听器关联的 CA 证书 ID。该参数用于 HTTPS 监听器的双向认证。 CACertificateSource 的值为 pca_sub 时，必须指定 PcaSubCACertificateId 参数。 **LoadBalancerId** string %%require%% `示例值：alb-abcderf******` 监听器所属的ALB实例ID。 **CertificateId** string `可选` `示例值：cert-********` 监听器关联的证书ID，创建 HTTPS 监听器且证书来源为 alb 时必传。 **ServerGroupId** string %%require%% `示例值：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个，取值1～20。 **DomainExtensions.N.PcaLeafCertificateId** string[] `可选` `示例值：DomainExtensions.1.PcaLeafCertificateId=pca_leaf-qwertyuqwert&DomainExtensions.2.PcaLeafCertificateId=pca_leaf-zxcvbgasdfn` 域名使用的服务器证书。 * 当证书来源为 pca_leaf 时有效。 * 参数\-N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 **AccessLogRecordCustomizedHeadersEnabled** string `可选` `示例值：off` 监听器开启/关闭访问日志记录Header。取值如下： * on：开启。 * off（默认值）：关闭。 ## 返回参数下方仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6369/80336)。 **RequestId** string `示例值：20210811152539010225146063030****` 请求 ID。 **ListenerId** string `示例值：lsn-2fek3rgsxhrsw5oxruwec****` 监听器 ID。 ## 请求示例 ```text GET /?Action=CreateListener&CertificateId=&Description=test&Enabled=on&ListenerName=TEST&LoadBalancerId=alb-1g1f1c6a****88ibuxws5k0k3&Port=12&Protocol=HTTP&ServerGroupId=rsp-2ff2u2282****5oxruwe33hdz&Version=2020-04-01" 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": "CreateListener", "Version": "2020-04-01", "Service": "alb", "Region": "cn-beijing" }, "Result": { "RequestId": "202108161106****22514606306AF947C", "ListenerId": "lsn-1g0swqx5fnqbk8ibuxyfxp2rd" } } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](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 |InvalidPort.Malformed |The specified Port is malformed. |指定的 Port 参数格式不合法。 | |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 |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 |InvalidAclType.Malformed |The specified AclType is malformed. |指定的 AclType 参数格式不合法。 | |400 |InvalidAclId.Duplicated |The specified AclId is duplicated. |指定的 AclId 重复。 | |400 |OperationFailed.QueryProject |The request on the specified resource failed due to the query on project failed. |因查询项目失败，对于该资源的操作请求失败。 | |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 |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 |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.Certificate.InvalidStatus |The specified DomainExtension Certificate is not in the correct status for the request. |指定的扩展域名证书所处状态无法响应该请求。 | |400 |InvalidCACertificate.InvalidStatus |The specified CA Certificate is not in the correct status for the request. |指定的 CA 证书所处状态无法响应该请求。 | |400 |InvalidProtocol.Malformed |The specified Protocol is malformed. |指定的 Protocol 参数格式不合法。 | |400 |InvalidEnabled.Malformed |The specified Enabled is malformed. |指定的 Enabled 参数格式不合法。 | |400 |InvalidEnableHttp2.Malformed |The specified EnableHttp2 is malformed. |指定的 EnableHttp2 参数格式不合法。 | |400 |InvalidEnableQuic.Malformed |The specified EnableQuic is malformed. |指定的 EnableQuic 参数格式不合法。 | |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 |OperationFailed.OperateGtmFailed |The request on the specified resource failed due to operating gtm failed. |因操作 GTM 实例失败，对于该资源的操作请求失败。 | |400 |OperationFailed.AddIntoProjectFailed |The request on the specified resource failed due to adding it into the project failed. |因将资源加入至项目中失败，对于该资源的操作请求失败。 | |400 |QuotaExceed.ListenerPerInstance |You've reached the limit on the number of listeners per ALB you can add in, resource xxx, usage xx/xx. |已达到每个 ALB 实例可创建的监听器的数量上限。资源是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 |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.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 |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 |InvalidDomainExtensions.CertificateSource.Malformed |The specified DomainExtensions.CertificateSource is malformed. |指定的 DomainExtensions.CertificateSource 参数格式不合法。 | |400 |OperationFailed.QueryCertificateService |The request on the specified resource failed due to the query on Certificate Service failed. |因请求证书中心服务失败，对于该资源的操作请求失败。 | |400 |OperationFailed.QueryIAM |The request on the specified resource failed due to the query on IAM failed. |因请求 IAM 失败，对于该资源的操作请求失败。 | |400 |InvalidCertificateSource.Malformed |The specified CertificateSource is malformed. |指定的 CertificateSource 参数格式不合法。 | |400 |InvalidProxyProtocolDisabled.Malformed |The specified ProxyProtocolDisabled is malformed. |指定的 ProxyProtocolDisabled 参数不合法。 | |400 |OperationFailed.AddTagFailed |The request on the specified resource failed due to adding tag to the resource failed. |因给资源添加标签失败，对于该资源的操作请求失败。 | |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 |InvalidTags.Key.Malformed |The specified Tags.Key is malformed. |指定的 Tags.Key 参数格式不合法。 | |400 |InvalidTags.Value.Malformed |The specified Tags.Value is malformed. |指定的 Tags.Value 参数格式不合法。 | |400 |InvalidTags.Key.Duplicated |The specified Tags.Key is duplicated. |指定的 Tags.Key 重复。 | |400 |InvalidXRealIpEnabled.Malformed |The specified XRealIpEnabled is malformed. |指定的 XRealIpEnabled 参数格式不合法。 | |403 |Forbidden |You are not authorized to enable quic for listener. |您无权限对监听器启用 Quic 。 | |403 |Forbidden |You are not authorized to disable X\-real\-ip header. |您无权限禁用 X\-real\-ip header。 | |404 |InvalidLoadBalancer.NotFound |The specified LoadBalancer does not exist. |指定的 ALB 实例不存在。 | |404 |InvalidServerGroup.NotFound |The specified ServerGroup does not exist. |指定的服务器组不存在。 | |404 |InvalidAcl.NotFound |The specified ACL does not exist. |指定的 ACL 不存在。 | |404 |InvalidProject.NotFound |The specified Project does not exist. |指定的项目不存在。 | |404 |InvalidServerCertificate.NotFound |The specified Server Certificate does not exist. |指定的服务器证书不存在。 | |404 |InvalidDomainExtensions.Certificate.NotFound |The specified DomainExtension Certificate does not exist. |指定的扩展域名证书不存在。 | |404 |InvalidCACertificate.NotFound |The specified CA Certificate does not exist. |指定的 CA 证书不存在。 | |409 |InvalidPort.Conflict |The specified Port already exists. |指定的端口已存在。 | |500 |InternalError |An internal error has occurred. |发生内部错误。请稍后重试或联系工程师进一步咨询。 |