调用 DescribeListeners 接口，查询监听器列表。 ## 使用说明 * 每秒最多提交 200 个 API 请求。 * 传入多个请求参数，按照传入的参数进行查询，返回符合所有条件的监听器，若没有符合条件的监听器，则返回空值。 * 若请求参数非必选参数均未传入，则按照当前登录账号查询，返回当前账号下的所有监听器。 ## 调试 ## 请求参数 **Action** `String` %%require%% 示例值：`DescribeListeners` 接口名称。当前 API 的名称为 `DescribeListeners`。 **Version** `String` %%require%% 示例值：`2020-04-01` 接口版本。当前 API 的版本为 `2020-04-01`。 **LoadBalancerId** `String` `可选` 示例值：`alb-*********` ALB实例ID。 **ListenerIds.N** `String[]` `可选` 示例值：`ListenerIds.1=lsn-abc*****&ListenerIds.2=lsn-def*******` 监听器的ID。 * 参数\-N：代表监听器的序号，一次查询数量上限为20个。 * 多个监听器的ID之间用&分隔。 **ListenerName** `String` `可选` 示例值：`test` 监听器的名称。 **Protocol** `String` `可选` 示例值：`HTTPS` 监听器的协议。取值如下： * HTTP。 * HTTPS。 **PageSize** `Integer` `可选` 示例值：`20` 分页查询时每页的记录数，取值1\-100，默认为10。 **PageNumber** `Integer` `可选` 示例值：`1` 列表的页码，默认值为1。 **ProjectName** `String` `可选` 示例值：`default` 监听器所属项目名称。 **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监听器。 * 多个标签值之间用&分隔。 :::tip 若传入该参数，则必须先传入TagFilters.N.Key。传入空字符串时，表示查询标签值为空的ALB监听器。 ::: ## 返回参数 **RequestId** `String` `可选` 示例值：`20210816110638****2514606306AF947C` 请求ID。 **PageSize** `Integer` `可选` 示例值：`20` 当前分页的记录数。 **PageNumber** `Integer` `可选` 示例值：`1` 当前页码。 **TotalCount** `Integer` `可选` 示例值：`26` 符合条件的监听器总数。 **Listeners** `Object[]` `可选` 示例值：`-` 符合条件的监听器的详细信息。 **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` `可选` 证书的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 时生效。 ## 请求示例 ```JSON 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": "20210816110638****2514606306AF947C", "Action": "DescribeListeners", "Version": "2020-04-01", "Service": "alb", "Region": "cn-beijing" }, "Result": { "RequestId": "20210814160835****2514606300FFE0F3", "PageNumber": 1, "PageSize": 20, "TotalCount": 1, "Listeners": [ { "CreateTime": "2021-12-14T11:13:40+08:00", "UpdateTime": "2021-12-14T11:13:41+08:00", "ListenerId": "lsn-1g0swr****gu88ibuxwmboj9h", "ListenerName": "test", "Enabled": "on", "Protocol": "HTTP", "Port": 80, "Status": "Active", "ServerGroupId": "rsp-2ff2u228****w5oxruwe33hdz", "ServerGroups": [ { "ServerGroupId": "rsp-2134****1234", "ServerGroupName": "pool-1", }, { "ServerGroupId": "rsp-2134****1234", "ServerGroupName": "pool-2", } ] }, { "CreateTime": "2021-12-14T11:13:40+08:00", "UpdateTime": "2021-12-14T11:13:41+08:00", "ListenerId": "lsn-1g0swr****gu88ibuxwmboj9h", "ListenerName": "test", "Enabled": "on", "Protocol": "HTTP", "Port": 81, "Status": "Active", "ServerGroupId": "rsp-2ff2u228****w5oxruwe33hdz", "ServerGroups": [ { "ServerGroupId": "rsp-2134****1234", "ServerGroupName": "pool-1", }, { "ServerGroupId": "rsp-2134****1234", "ServerGroupName": "pool-2", } ] }, { "CreateTime":"2022-02-28T07:43:01Z", "UpdateTime":"2022-03-01T08:22:22Z", "ListenerId":"lsn-2feosm67lyghs5oxruw0b6b2z", "ListenerName":"yxl-listener", "Description":"", "AclStatus":"on", "AclType":"black", "AclIds":[ "acl-2fecyh9olyp6o5oxruw586umy" ], "Enabled":"on", "Protocol":"HTTP", "Port":82, "Status":"Active", "ServerGroupId":"rsp-2fe90sy6j32805oxruw5eyjq7", "CertificateId":"", "ServerGroups":[ { "ServerGroupId":"rsp-2fe90sy6j32805oxruw5eyjq7", "ServerGroupName":"default" } ] } ] } } ``` ## 错误码如果响应正文包含 Error 字段，则表示 API 请求失败。此处仅展示当前 API 的错误码，更多错误码请参见[公共错误码](https://www.volcengine.com/docs/6406/113579)。 |**状态码** |**错误码** |**错误信息** |**说明** | |---|---|---|---| |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 参数格式不合法。 |