Creates an HTTP, HTTPS, or QUIC listener.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateListener

The operation that you want to perform.

Set the value to CreateListener.

LoadBalancerId String Yes lb-bp1o94dp5i6ea****

The ID of the Application Load Balancer (ALB) instance.

You can call the DescribeRegions operation to query the most recent region list.

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

The client token that is used to ensure the idempotence of the request.

You can use the client to generate the value, but you must make sure that it is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

Note If you do not set this parameter, the system automatically uses RequestId as ClientToken. RequestId may be different for each API request.
DryRun Boolean No false

Specifies whether to only precheck this request. Valid values:

  • true: prechecks the request without creating the resource. The system checks the required parameters, request syntax, and limits. If the request fails to pass the precheck, an error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false (default): sends the API request. If the request passes the precheck, a 2xx HTTP status code is returned and the operation is performed.
ListenerProtocol String Yes HTTP

The listening protocol.

Valid values: HTTP, HTTPS, and QUIC.

ListenerPort Integer Yes 80

The frontend port that is used by the ALB instance.

Valid values: 1 to 65535.

ListenerDescription String No test

The description of the listener.

The description must be 2 to 256 characters in length, and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), and underscores (_). Regular expressions are supported.

RequestTimeout Integer No 60

The timeout period of a request. Unit: seconds.

Valid values: 1 to 180.

Default value: 60.

If no response is received from the backend server during the request timeout period, ALB sends an HTTP 504 error code to the client.

IdleTimeout Integer No 3

The timeout period of an idle connection. Unit: seconds.

Valid values: 1 to 60.

Default value: 15.

If no request is received within the specified timeout period, ALB closes the current connection. When another request is received, ALB establishes a new connection.

GzipEnabled Boolean No true

Specifies whether to enable Gzip compression to compress specific types of files. Valid values:

  • true (default): enables gzip compression.
  • false: disables gzip compression.
Http2Enabled Boolean No true

Specifies whether to enable HTTP/2. Valid values:

  • true (default): enables HTTP/2.
  • false: disables HTTP/2.
Note Only HTTPS listeners support this parameter.
SecurityPolicyId String No tls_cipher_policy_1_0

The ID of the security policy. System security policies and custom security policies are supported.

Default value: tls_cipher_policy_1_0 (system security policy).

Note Only HTTPS listeners support this parameter.
CaEnabled Boolean No false

Specifies whether to enable mutual authentication. Valid values:

  • true: enables mutual authentication.
  • false (default): disables mutual authentication.
XForwardedForConfig Object No

The configuration of the XForward header.

XForwardedForClientCertClientVerifyAlias String No test_client-verify-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertClientVerifyEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain lowercase letters, hyphens (-), underscores (_), and digits.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertClientVerifyEnabled Boolean No false

Specifies whether to use the X-Forwarded-Clientcert-clientverify header to retrieve the verification result of the client certificate. Valid values:

  • true: yes.
  • false (default): no.
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintAlias String No test_finger-print-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertFingerprintEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain lowercase letters, hyphens (-), underscores (_), and digits.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintEnabled Boolean No false

Specifies whether to use the X-Forwarded-Clientcert-fingerprint header to retrieve the fingerprint of the client certificate. Valid values:

  • true: yes.
  • false (default): no.
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNAlias String No test_issue-dn-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain lowercase letters, hyphens (-), underscores (_), and digits.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNEnabled Boolean No false

Specifies whether to use the X-Forwarded-Clientcert-issuerdn header to retrieve information about the authority that issues the client certificate. Valid values:

  • true: yes.
  • false (default): no.
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNAlias String No test_subject-dn-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain lowercase letters, hyphens (-), underscores (_), and digits.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNEnabled Boolean No false

Specifies whether to use the X-Forwarded-Clientcert-subjectdn header to retrieve information about the owner of the client certificate. Valid values:

  • true: yes.
  • false (default): no.
Note Only HTTPS listeners support this parameter.
XForwardedForClientSrcPortEnabled Boolean No false

Specifies whether to use the X-Forwarded-Client-Port header to retrieve the client port. Valid values:

  • true: yes.
  • false (default): no.
Note HTTP and HTTPS listeners support this parameter.
XForwardedForEnabled Boolean No false

Specifies whether to use the X-Forwarded-For header to retrieve client IP addresses. Valid values:

  • true: yes.
  • false (default): no.
Note HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean No false

Specifies whether to use the X-Forwarded-Proto header to retrieve the listening protocol. Valid values:

  • true: yes.
  • false (default): no.
Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBIdEnabled Boolean No false

Specifies whether to use the SLB-ID header to retrieve the ID of the ALB instance. Valid values:

  • true: yes.
  • false (default): no.
Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBPortEnabled Boolean No false

Specifies whether to use the X-Forwarded-Port header to retrieve the listening port of the ALB instance. Valid values:

  • true: yes.
  • false (default): no.
Note HTTP, HTTPS, and QUIC listeners support this parameter.
QuicConfig Object No

The configuration of the QUIC listener that you want to associate with the current listener.

QuicListenerId String No lsr-bp1bpn0kn908w4nbw****

The ID of the QUIC listener that you want to associate with the HTTPS listener. Only HTTPS listeners support this parameter. This parameter is required when QuicUpgradeEnabled is set to true.

Note The HTTPS listener and the associated QUIC listener must be added to the same ALB instance. In addition, make sure that the QUIC listener is not associated with another listener.
QuicUpgradeEnabled Boolean No false

Specifies whether to enable QUIC upgrade. Valid values:

  • true: enables QUIC upgrade.
  • false (default): disables QUIC upgrade.
Note Only HTTPS listeners support this parameter.
Certificates Array No

The list of certificates.

CertificateId String No 12315790212_166f8204689_1714763408_70998****

The ID of the certificate. Only server certificates are supported.

DefaultActions Array Yes

The actions of the forwarding rule.

ForwardGroupConfig Object Yes

The configuration of the action.

ServerGroupTuples Array Yes

The server group to which requests are forwarded.

ServerGroupId String Yes rsp-cige6j****

The ID of the server group to which requests are forwarded.

Type String Yes ForwardGroup

The type of the action.

If ForwardGroup is returned, it indicates that requests are forwarded to multiple vServer groups.

Response parameters

Parameter Type Example Description
JobId String 72dcd26b-f12d-4c27-b3af-18f6aed5****

The ID of the asynchronous task.

ListenerId String lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

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

The ID of the request.

Examples

Sample requests

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

Sample success responses

XML format 

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 format 

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

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

Error codes

HttpCode Error code Error message Description
400 ResourceAlreadyExist.Listener The specified resource %s is already exist. The error message returned because the specified %s resource already exists.
400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect. The error message returned because the status of the specified resource %s [%s] is invalid.
400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s]  is incorrect. The error message returned because the service status of the specified resource %s [%s] is invalid.
400 ResourceQuotaExceeded.LoadBalancerListenersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. The error message returned because the operation is not allowed due to %s.
400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. The error message returned because the specified %s resource is already associated.
400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 Mismatch.VpcId The %s is mismatched for %s and %s. The error message returned because %s does not correspond to %s and %s.
400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. The error message returned because the specified server group protocol is invalid.
404 ResourceNotFound.LoadBalancer The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.ServerGroup The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.Listener The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.Certificate The specified resource %s is not found. The error message returned because the specified resource %s does not exist.

For a list of error codes, visit the API Error Center.