调用CreateListener接口为应用型负载均衡创建HTTP、HTTPS或QUIC监听。

使用说明

CreateListener接口属于异步接口,即系统返回一个请求ID,但该HTTP、HTTPS或QUIC监听尚未创建成功,系统后台的创建任务仍在进行。您可以调用GetListenerAttribute查询HTTP、HTTPS或QUIC监听的创建状态:

  • 当HTTP、HTTPS或QUIC监听处于Provisioning状态时,表示HTTP、HTTPS或QUIC监听正在创建中。
  • 当HTTP、HTTPS或QUIC监听处于Running状态时,表示HTTP、HTTPS或QUIC监听创建成功。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String CreateListener

系统规定的参数。取值:CreateListener

LoadBalancerId String lb-bp1o94dp5i6ea****

应用型负载均衡实例ID。

ClientToken String 123e4567-e89b-12d3-a456-426655440000

客户端Token,用于保证请求的幂等性。

从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken只支持ASCII字符。

说明 若您未指定,则系统自动使用API请求的RequestId作为ClientToken标识。每次API请求的RequestId可能不一样。
DryRun Boolean false

是否只预检此次请求,取值:

  • true:发送检查请求,不会创建监听。检查项包括是否填写了必需参数、请求格式、业务限制。如果检查不通过,则返回对应错误。如果检查通过,则返回错误码DryRunOperation
  • false(默认值):发送正常请求,通过检查后返回HTTP 2xx状态码并直接进行操作。
ListenerProtocol String HTTP

监听协议。

取值:HTTPHTTPSQUIC

ListenerPort Integer 80

负载均衡实例前端使用的端口。

取值:1~65535

ListenerDescription String HTTP_80

自定义监听名称。

长度为2~256个字符,必须是中文和无害字符串中的字符,可包含中文、字母、数字、短划线(-)、正斜线(/)、半角句号(.)、下划线(_)。

RequestTimeout Integer 60

指定请求超时时间。单位:秒。

取值:1~180

默认值:60

如果在超时时间内后端服务器一直没有响应,负载均衡将放弃等待,并给客户端返回 HTTP 504 错误码。

IdleTimeout Integer 3

指定连接空闲超时时间。单位:秒。

取值范围:1~60

默认值:15

如果在超时时间内一直没有访问请求,负载均衡会暂时中断当前连接,直到一下次请求来临时重新建立新的连接。

GzipEnabled Boolean true

是否开启Gzip压缩,对特定文件类型进行压缩。取值:

  • true(默认值):是。
  • false:否。
Http2Enabled Boolean true

是否开启HTTP/2特性。取值:

  • true(默认值):是。
  • false:否。
说明 仅HTTPS监听支持此参数。
SecurityPolicyId String tls_cipher_policy_1_0

安全策略ID。支持系统安全策略和自定义安全策略。

默认值:tls_cipher_policy_1_0(系统安全策略)。

说明 仅HTTPS监听支持此参数。
CaEnabled Boolean false

是否开启双向认证。取值:

  • true:开启。
  • false(默认值):不开启。
XForwardedForConfig.XForwardedForClientCertClientVerifyAlias String test_client-verify-alias_123456

自定义头名称,只有当XForwardedForClientCertClientVerifyEnabled的值为true的时候,该值才会生效;否则该值不会生效。

取值:1~40个字符。支持字母a~z、短划线(-)、下划线(_)和数字。

说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertClientVerifyEnabled Boolean true

是否通过X-Forwarded-Clientcert-clientverify头字段获取对访问负载均衡实例客户端证书的校验结果。取值:

  • true:是。
  • false(默认值):否。
说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertFingerprintAlias String test_finger-print-alias_123456

自定义头名称,只有当XForwardedForClientCertFingerprintEnabled的值为true时生效。

取值:1~40个字符。支持字母a~z、短划线(-)、下划线(_)和数字。

说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertFingerprintEnabled Boolean true

是否通过X-Forwarded-Clientcert-fingerprint头字段获取访问负载均衡实例客户端证书的指纹取值。取值:

  • true:是。
  • false(默认值):否。
说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertIssuerDNAlias String test_issue-dn-alias_123456

自定义头名称,只有当XForwardedForClientCertIssuerDNEnabled的值为true的时候,此值才会生效。

取值:1~40个字符。支持字母a~z、短划线(-)、下划线(_)和数字。

说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertIssuerDNEnabled Boolean true

是否通过X-Forwarded-Clientcert-issuerdn头字段获取访问负载均衡实例客户端证书的发行者信息。取值:

  • true:是。
  • false(默认值):否。
说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertSubjectDNAlias String test_subject-dn-alias_123456

自定义头名称,只有当XForwardedForClientCertSubjectDNEnabled的值为true时,此值才会生效。

取值:1~40个字符。支持字母a~z、短划线(-)、下划线(_)和数字。

说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientCertSubjectDNEnabled Boolean true

是否通过X-Forwarded-Clientcert-subjectdn头字段获取访问负载均衡实例客户端证书的所有者信息。取值:

  • true:是。
  • false(默认值):否。
说明 仅HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForClientSrcPortEnabled Boolean true

是否通过X-Forwarded-Client-Port头字段获取访问负载均衡实例客户端的端口。取值:

  • true:是。
  • false(默认值):否。
说明 HTTP和HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForEnabled Boolean true

是否通过X-Forwarded-For头字段获取来访者真实IP。取值:

  • true(默认值):是。
  • false:否。
说明 HTTP和HTTPS监听支持此参数。
XForwardedForConfig.XForwardedForProtoEnabled Boolean false

是否通过X-Forwarded-Proto头字段获取负载均衡实例的监听协议。取值:

  • true:是。
  • false(默认值):否。
说明 HTTP、HTTPS和QUIC监听支持此参数。
XForwardedForConfig.XForwardedForSLBIdEnabled Boolean false

是否通过SLB-ID头字段获取负载均衡实例ID。取值:

  • true:是。
  • false(默认值):否。
说明 HTTP、HTTPS和QUIC监听支持此参数。
XForwardedForConfig.XForwardedForSLBPortEnabled Boolean false

是否通过X-Forwarded-Port头字段获取负载均衡实例的监听端口。取值:

  • true:是。
  • false(默认值):否。
说明 HTTP、HTTPS和QUIC监听支持此参数。
XForwardedForConfig.XForwardedForClientSourceIpsEnabled Boolean false

是否通过X-Forwarded-Client-Ip头字段获取访问负载均衡实例的源IP。取值:

  • true:是。
  • false(默认值):否。
说明 HTTP、HTTPS和QUIC监听支持此参数。该参数对应的功能默认不开放,如需使用请联系客户经理。
XForwardedForConfig.XForwardedForClientSourceIpsTrusted String 10.1.1.0/24

指定可信的代理IP。

应用型负载均衡ALB会从后往前遍历X-Forwarded-For,选取第一个不在可信IP列表中的IP作为真实的客户端IP,该IP会被用于源IP限速。

QuicConfig.QuicListenerId String lsr-bp1bpn0kn908w4nbw****

需要关联的QUIC监听ID,HTTPS监听时有效,当QuicUpgradeEnabledtrue时该参数必选。

说明 原始监听和关联的QUIC监听必须属于同一个ALB实例,并且此QUIC监听之前没有被关联过。
QuicConfig.QuicUpgradeEnabled Boolean false

是否开启QUIC升级。取值:

  • true:是。
  • false(默认值):否。
说明 仅HTTPS监听支持此参数。
Certificates.N.CertificateId String 12315790212_166f8204689_1714763408_70998****

证书ID,当前仅支持服务器证书。最多支持添加20个证书ID。

DefaultActions.N.ForwardGroupConfig.ServerGroupTuples.N.ServerGroupId String rsp-cige6j****

转发到的目的服务器组ID。

DefaultActions.N.Type String ForwardGroup

动作类型。最多支持添加1个动作类型。

取值:ForwardGroup,表示转发至多个虚拟服务器组。

返回数据

名称 类型 示例值 描述
JobId String 72dcd26b-f12d-4c27-b3af-18f6aed5****

异步任务ID。

ListenerId String lsr-bp1bpn0kn908w4nbw****

监听ID。

RequestId String CEF72CEB-54B6-4AE8-B225-F876FF7BA984

请求ID。

示例

请求示例

http(s)://[Endpoint]/?Action=CreateListener
&LoadBalancerId=lb-bp1o94dp5i6ea****
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&DryRun=false
&ListenerProtocol=HTTP
&ListenerPort=80
&ListenerDescription=HTTP_80
&RequestTimeout=60
&IdleTimeout=3
&GzipEnabled=true
&Http2Enabled=true
&SecurityPolicyId=tls_cipher_policy_1_0
&CaEnabled=false
&XForwardedForConfig={"XForwardedForClientCertClientVerifyAlias":"test_client-verify-alias_123456","XForwardedForClientCertClientVerifyEnabled":true,"XForwardedForClientCertFingerprintAlias":"test_finger-print-alias_123456","XForwardedForClientCertFingerprintEnabled":true,"XForwardedForClientCertIssuerDNAlias":"test_issue-dn-alias_123456","XForwardedForClientCertIssuerDNEnabled":true,"XForwardedForClientCertSubjectDNAlias":"test_subject-dn-alias_123456","XForwardedForClientCertSubjectDNEnabled":true,"XForwardedForClientSrcPortEnabled":true,"XForwardedForEnabled":true,"XForwardedForProtoEnabled":false,"XForwardedForSLBIdEnabled":false,"XForwardedForSLBPortEnabled":false,"XForwardedForClientSourceIpsEnabled":false,"XForwardedForClientSourceIpsTrusted":"10.1.1.0/24"}
&QuicConfig={"QuicListenerId":"lsr-bp1bpn0kn908w4nbw****","QuicUpgradeEnabled":false}
&Certificates=[{"CertificateId":"12315790212_166f8204689_1714763408_70998****"}]
&CaCertificates=[null]
&DefaultActions=[{"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"rsp-cige6j****"}]},"Type":"ForwardGroup"}]
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateListenerResponse>
    <JobId>72dcd26b-f12d-4c27-b3af-18f6aed5****</JobId>
    <ListenerId>lsr-bp1bpn0kn908w4nbw****</ListenerId>
    <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId>
</CreateListenerResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

{
  "JobId" : "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "ListenerId" : "lsr-bp1bpn0kn908w4nbw****",
  "RequestId" : "CEF72CEB-54B6-4AE8-B225-F876FF7BA984"
}

错误码

HttpCode 错误码 错误信息 描述
400 ResourceAlreadyExist.Listener The specified resource %s is already exist. 资源%s已存在。
400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect. 资源%s [%s]的状态无效。
400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s]  is incorrect. 资源%s [%s]的业务状态无效。
400 ResourceQuotaExceeded.LoadBalancerListenersNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制,资源是%s,目前已使用%s,配额为%s。
400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. 操作被拒绝,原因是%s。
400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. 资源%s已被关联。
400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制,资源是%s,目前已使用%s,配额为%s。
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制,资源是%s,目前已使用%s,配额为%s。
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制,资源是%s,目前已使用%s,配额为%s。
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制,资源是%s,目前已使用%s,配额为%s。
400 Mismatch.VpcId The %s is mismatched for %s and %s. %s在%s和%s中不匹配。
400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. 操作被拒绝,原因是ServerGroupProtocolNotSupport。
404 ResourceNotFound.LoadBalancer The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.ServerGroup The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.Listener The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.Certificate The specified resource %s is not found. 资源%s不存在。

访问错误中心查看更多错误码。