调用 DescribeListeners 接口，查询监听器列表。 ## 使用说明 * 每秒最多提交 200 个 API 请求。 * 传入多个请求参数，按照传入的参数进行查询，返回符合所有条件的监听器，若没有符合条件的监听器，则返回空值。 * 若请求参数非必选参数均未传入，则按照当前登录账号查询，返回当前账号下的所有监听器。 ## 请求说明 * 请求方式：**GET** * 请求地址： **/?Action=DescribeListeners&Version=2020\-04\-01** ## 调试 [去调试](https://api.volcengine.com/api-explorer/?action=DescribeListeners&groupName=%E7%9B%91%E5%90%AC%E5%99%A8&serviceCode=alb&version=2020-04-01) ## 请求参数下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6369/67268)。 **Action** string 必选 `示例值：DescribeListeners` 要执行的操作，取值：DescribeListeners。 **Version** string 必选 `示例值：2020-04-01` API的版本，取值：2020\-04\-01。 **TagFilters.N.Key** string[] `可选` `示例值：TagFilters.1.Key=k1&TagFilters.2.Key=k2` 标签的标签键。 * 参数 \- N：表示标签键的序号，取值范围：1～10。 * 多个标签键之间用&分隔。多个标签键之间的关系为逻辑“与（AND）”，即查询同时添加多个标签键的ALB监听器。 * 不允许重复。 **TagFilters.N.Values.N** string[] `可选` `示例值：TagFilters.1.Value.1=v1&TagFilters.1.Value.2=v2&TagFilters.2.Value.1=v3` 标签的标签值。 * 第一个N：表示标签键的序号，取值范围：1～10。 * 第二个N：表示标签值的序号，取值范围：1～3。同一标签键多个标签值之间的关系为逻辑“或(OR)”，即查询同一标签键下添加其中一个标签值的ALB监听器。 * 多个标签值之间用&分隔。

说明

若传入该参数，则必须先传入TagFilters.N.Key。

传入空字符串时，表示查询标签值为空的ALB监听器。

**ListenerName** string `可选` `示例值：test` 监听器的名称。 **LoadBalancerId** string `可选` `示例值：alb-*********` ALB实例ID。 **PageNumber** integer `可选` `示例值：1` 列表的页码，默认值为1。 **PageSize** integer `可选` `示例值：20` 分页查询时每页的记录数，取值1\-100，默认为10。 **ListenerIds.N** string[] `可选` `示例值：ListenerIds.1=lsn-abc*****&ListenerIds.2=lsn-def*******` 监听器的ID。 * 参数\-N：代表监听器的序号，一次查询数量上限为20个。 * 多个监听器的ID之间用&分隔。 **Protocol** string `可选` `示例值：HTTPS` 监听器的协议。取值如下： * HTTP。 * HTTPS。 **ProjectName** string `可选` `示例值：default` 监听器所属项目名称。 ## 返回参数下方仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6369/80336)。 **RequestId** string `示例值：20210816110638****2514606306AF947C` 请求ID。 **PageSize** integer `示例值：20` 当前分页的记录数。 **PageNumber** integer `示例值：1` 当前页码。 **TotalCount** integer `示例值：26` 符合条件的监听器总数。 **Listeners** object[] `示例值：--` 符合条件的监听器的详细信息。 **XRealIpEnabled** string `示例值：on` 监听器开启/禁用请求中的X\-Real\-IP头字段。取值如下： * on：开启。 * off：关闭。 **ListenerId** string `示例值：lsn-*******` 监听器ID。 **ListenerName** string `示例值：test` 监听器名称。 **CreateTime** string `示例值：2021-12-29T16:37:37Z` 监听器的创建时间。 **UpdateTime** string `示例值：2021-12-29T16:37:37Z` 监听器最近一次的操作时间。 **Status** string `示例值：Active` 监听器的状态。 * Creating：创建中。 * Active：运行中。 * Pending：变配中。 * Disabled：已停止。 * Deleting：删除中。 **Enabled** string `示例值：on` 是否启用监听器。 * on：开启。 * off：关闭。 **Protocol** string `示例值：HTTP` 监听器的协议。 **Port** integer `示例值：80` 监听器的监听端口。 **ServerGroupId** string `示例值：rsp-*******` 监听器的默认服务器组。 **ServerGroups** object[] `示例值：--` 关联监听器的所有服务器组的信息。 **ServerGroupId** string `示例值：rsp-888888` 服务器组 ID。 **ServerGroupName** string `示例值：pool` 服务器组名称。 **LoadBalancerId** string `示例值：alb-**********` 监听器所属的 ALB 实例 ID。 **Description** string `示例值：test` 监听器的描述信息。 **CertificateSource** string `示例值：cert_center` HTTPS监听器关联的默认证书的来源。 * alb：表示通过 ALB 上传的证书。 * cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 **CertificateId** string `示例值：cert-******` HTTPS监听器关联的证书 ID。当证书来源为 alb 时生效。 **CertCenterCertificateId** string `示例值：cert-******` HTTPS监听器关联的证书 ID。当证书来源为 cert_center 时生效。 **CACertificateSource** string `示例值：pca_root` HTTPS 监听器关联的 CA 证书的来源。 * alb：表示通过 ALB 上传的证书。 * pca_root：表示通过火山引擎证书中心购买或上传的私有根 CA 证书。 * pca_sub：表示通过火山证书中心购买或上传的私有子 CA 证书。 **CACertificateId** string `示例值：cert-******` HTTPS 监听器关联的 CA 证书 ID。当证书来源为 alb 时生效。 **PcaRootCACertificateId** string `示例值：cert-******` HTTPS 监听器关联的 CA 证书 ID。当证书来源是 pca_root 时生效。 **PcaSubCACertificateId** string `示例值：cert-******` HTTPS 监听器关联的 CA 证书 ID。当证书来源是 pca_sub 时生效。 **EnableHttp2** string `示例值：off` HTTP2.0 特性开关。 * on：开启。 * off：关闭。 **EnableQuic** string `示例值：off` QUIC 特性开关。 * on：开启。 * off：关闭。 **AclStatus** string `示例值：off` 是否开启访问控制功能。 * on：开启。 * off ：不开启。 **AclType** string `示例值：black` 访问控制的方式。 * white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器不会转发任何请求。 * black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器会转发全部请求。 **AclIds** string[] `示例值：["acl-2fe5excqgk6ww5oxruvcv****","acl-2febxt4pu0zy85oxruw0t****"]` 监听器绑定的访问控制策略组 ID，仅AclStatus参数为on时返回。 **CustomizedCfgId** string `示例值：ccfg-****` 个性化配置ID，未绑定时值为" "。 **DomainExtensions** object[] `示例值：--` HTTPS监听器关联的扩展域名列表。 **DomainExtensionId** string `示例值：dc-*******` 扩展域名 ID 。 **CertificateSource** string `示例值：cert_center` HTTPS监听器关联的默认证书的来源。 * alb：表示通过 ALB 上传的证书。 * cert_center：表示通过火山引擎证书中心购买或上传的 SSL 证书。 **CertificateId** string `示例值：cert-*****` 域名使用的服务器证书 ID 。当证书来源为 alb 时生效。 **CertCenterCertificateId** string `示例值：cert-******` 域名使用的服务器证书 ID。当证书来源为 cert_center 时生效。 **Domain** string `示例值：abc.com` 域名。 **ListenerId** string `示例值：lsn-****` 扩展域名所属的监听器 ID 。 **San** string `示例值：www.test.com,api.test.com,192.168.1.100` 证书的CommonName、扩展域名和IP，用‘，’分隔。 **PcaLeafCertificateId** string `示例值：cert-********` 域名使用的服务器证书 ID 。当证书来源为 pca_leaf 时生效。 **ProjectName** string `示例值：default` 监听器所属项目名称。 **Tags** object[] `示例值：--` 监听器所属标签。 **Key** string `示例值：key` 用户标签的标签键。 **Value** string `示例值：value` 用户标签的标签 **AccessLogRecordCustomizedHeadersEnabled** string `示例值：on` 监听器是否已开启“在访问日志中记录自定义header”的功能。 * on：表示该功能已开启。 * off：表示该功能未开启。 **PcaLeafCertificateId** string `示例值：cert-********` HTTPS监听器关联的证书 ID。当证书来源为 pca_leaf 时生效。 ## 请求示例 ```text GET /?Action=DescribeListeners&Version=2020-04-01&LoadBalancerId=alb-1g1f1c6aevm****buxws5k0k3&PageSize=20&PageNumber=1&ListenerIds.1=lsn-1g0swrgw****88ibuxwmboj9h&ListenerIds.2=lsn-1g0swrgw****88ibuxwmboj9h 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 ``` ## 返回示例 ```json { "ResponseMetadata": { "RequestId": "20260514193453156097164082FB6467", "Action": "DescribeListeners", "Version": "2020-04-01", "Service": "alb", "Region": "cn-beijing" }, "Result": { "RequestId": "20210816110638****2514606306AF947C", "PageSize": 20, "PageNumber": 1, "TotalCount": 26, "Listeners": [ { "XRealIpEnabled": "Sh56vblLvHl", "ListenerId": "lsn-*******", "ListenerName": "test", "CreateTime": "2021-12-29T16:37:37Z", "UpdateTime": "2021-12-29T16:37:37Z", "Status": "Active", "Enabled": "on", "Protocol": "HTTP", "Port": 80, "ServerGroupId": "rsp-*******", "ServerGroups": [ { "ServerGroupId": "rsp-888888", "ServerGroupName": "pool" } ], "LoadBalancerId": "alb-**********", "Description": "test", "CertificateSource": "cert_center", "CertificateId": "cert-******", "CertCenterCertificateId": "cert-******", "CACertificateSource": "pca_root", "CACertificateId": "cert-******", "PcaRootCACertificateId": "cert-******", "PcaSubCACertificateId": "cert-******", "EnableHttp2": "off", "EnableQuic": "off", "AclStatus": "off", "AclType": "black", "AclIds": [ "[\"acl-2fe5excqgk6ww5oxruvcv****\",\"acl-2febxt4pu0zy85oxruw0t****\"]" ], "CustomizedCfgId": "ccfg-****", "DomainExtensions": [ { "DomainExtensionId": "dc-*******", "CertificateSource": "cert_center", "CertificateId": "cert-*****", "CertCenterCertificateId": "cert-******", "Domain": "abc.com", "ListenerId": "lsn-****", "San": "2oMFmJuTh", "PcaLeafCertificateId": "cert-********" } ], "ProjectName": "default", "Tags": [ { "Key": "key", "Value": "value" } ], "AccessLogRecordCustomizedHeadersEnabled": "on", "PcaLeafCertificateId": "cert-********" } ] } } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](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 |InvalidPaging.Malformed |The specified PageNumber or PageSize is malformed. |指定的分页参数格式不合法。 | |400 |InvalidListenerName.Malformed |The specified ListenerName is malformed. |指定的 ListenerName 参数格式不合法。 | |400 |LimitExceed.Listener |You've reached the limit on the number of listeners that you can operate at a time. |已达到单次可操作的监听器的数量上限。 | |400 |InvalidProtocol.Malformed |The specified Protocol is malformed. |指定的 Protocol 参数格式不合法。 | |500 |InternalError |An internal error has occurred. |发生内部错误。请稍后重试或联系工程师进一步咨询。 |

负载均衡