Creates an HTTP, HTTPS, or QUIC listener.
Debugging
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:
|
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 |
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
|
Http2Enabled | Boolean | No | true |
Specifies whether to enable
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:
|
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
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
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
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
Note Only HTTPS listeners support this parameter.
|
XForwardedForClientSrcPortEnabled | Boolean | No | false |
Specifies whether to use the
Note HTTP and HTTPS listeners support this parameter.
|
XForwardedForEnabled | Boolean | No | false |
Specifies whether to use the
Note HTTP and HTTPS listeners support this parameter.
|
XForwardedForProtoEnabled | Boolean | No | false |
Specifies whether to use the
Note HTTP, HTTPS, and QUIC listeners support this parameter.
|
XForwardedForSLBIdEnabled | Boolean | No | false |
Specifies whether to use the
Note HTTP, HTTPS, and QUIC listeners support this parameter.
|
XForwardedForSLBPortEnabled | Boolean | No | false |
Specifies whether to use the
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:
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.