CreateListener - Server Load Balancer - Alibaba Cloud ドキュメントセンター

Creates a listener.

Operation description

Usage notes

CreateListener is an asynchronous operation. After you call this operation, the system returns a request ID. However, the operation is still being performed in the background. You can call the GetListenerAttribute operation to query the status of the HTTP, HTTPS, or QUIC listener.

If the HTTP, HTTPS, or QUIC listener is in the Provisioning state, it indicates that the listener is being created.
If the HTTP, HTTPS, or QUIC listener is in the Running state, it indicates that the listener has been created successfully.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- For mandatory resource types, indicate with a prefix of * .
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
alb:CreateListener	create	LoadBalancer `acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}` SecurityPolicy `acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}` *ServerGroup `acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}`	alb:ListenerProtocol	none

Request parameters

Parameter	Type	Required	Description	Example
LoadBalancerId	string	Yes	The ID of the ALB instance.	alb-n5qw04uq8vavfe****
ClientToken	string	No	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 all requests. The token can contain only ASCII characters. Note If you do not set this parameter, the system automatically uses the value of RequestId as the value of ClientToken. RequestId may be different for each API request.	123e4567-e89b-12d3-a456-426655440000
DryRun	boolean	No	Specifies whether to perform only a precheck. Valid values: true: prechecks the request without creating a listener. The system checks the required parameters, request syntax, and limits. If the request fails the precheck, an error code is returned based on the cause of the failure. 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 system proceeds to create a listener.	false
ListenerProtocol	string	Yes	The listener protocol. Valid values: HTTP, HTTPS, and QUIC.	HTTP
ListenerPort	integer	Yes	The frontend port that is used by the ALB instance. Valid values: 1 to 65535.	80
ListenerDescription	string	No	The name 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.	HTTP_80
RequestTimeout	integer	No	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.	60
IdleTimeout	integer	No	The timeout period of an idle connection. Unit: seconds. Valid values: 1 to 60. Default value: 15. If no requests are received within the specified timeout period, ALB closes the current connection. When a new request is received, ALB establishes a new connection.	3
GzipEnabled	boolean	No	Specifies whether to enable `Gzip` compression to compress specific types of files. Valid values: true (default): enables Gzip compression. false: disables Gzip compression.	true
Http2Enabled	boolean	No	Specifies whether to enable `HTTP/2`. Valid values: true (default): enables HTTP/2. false: disables HTTP/2. Note Only HTTPS listeners support this parameter.	true
SecurityPolicyId	string	No	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.	tls_cipher_policy_1_0
CaEnabled	boolean	No	Specifies whether to enable mutual authentication. Valid values: true: enables mutual authentication. false (default): disables mutual authentication.	false
XForwardedForConfig	object	No	The configuration of the XForward header.
XForwardedForClientCertClientVerifyAlias	string	No	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.	test_client-verify-alias_123456
XForwardedForClientCertClientVerifyEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-clientverify` header to retrieve the verification result of the client certificate. Valid values: true: uses the X-Forwarded-Clientcert-clientverify header. false (default): does not use the X-Forwarded-Clientcert-clientverify header. Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertFingerprintAlias	string	No	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.	test_finger-print-alias_123456
XForwardedForClientCertFingerprintEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-fingerprint` header to retrieve the fingerprint of the client certificate. Valid values: true: uses the X-Forwarded-Clientcert-fingerprint header. false (default): does not use the X-Forwarded-Clientcert-fingerprint header. Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertIssuerDNAlias	string	No	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.	test_issue-dn-alias_123456
XForwardedForClientCertIssuerDNEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-issuerdn` header to retrieve information about the authority that issues the client certificate. Valid values: true: uses the X-Forwarded-Clientcert-issuerdn header. false (default): does not use the X-Forwarded-Clientcert-issuerdn header. Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertSubjectDNAlias	string	No	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.	test_subject-dn-alias_123456
XForwardedForClientCertSubjectDNEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-subjectdn` header to retrieve information about the owner of the client certificate. Valid values: true: uses the X-Forwarded-Clientcert-subjectdn header. false (default): does not use the X-Forwarded-Clientcert-subjectdn header. Note Only HTTPS listeners support this parameter.	true
XForwardedForClientSrcPortEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Client-srcport` header to retrieve the client port. Valid values: true: uses the X-Forwarded-Client-srcport header. false (default): does not use the X-Forwarded-Client-srcport header. Note HTTP and HTTPS listeners support this parameter.	true
XForwardedForEnabled	boolean	No	Specifies whether to use the `X-Forwarded-For` header to retrieve client IP addresses. Valid values: true (default) false Note HTTP and HTTPS listeners support this parameter.	true
XForwardedForProcessingMode	string	No	Specifies how the `X-Forwarded-For` header is processed. This parameter takes effect only when XForwardedForEnabled is set to true. Valid values: append (default) remove Note If this parameter is set to append, ALB appends the IP address of the last hop to the existing `X-Forwarded-For` header in the request before the request is sent to backend servers. If this parameter is set to remove, ALB removes the `X-Forwarded-For` header in the request before the request is sent to backend servers, no matter whether the request carries the `X-Forwarded-For` header. This parameter is only available for HTTP and HTTPS listeners.	append
XForwardedForProtoEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Proto` header to retrieve the listener protocol of the ALB instance. Valid values: true: uses the X-Forwarded-Proto header. false (default): does not use the X-Forwarded-Proto header. Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForSLBIdEnabled	boolean	No	Specifies whether to use the `SLB-ID` header to retrieve the ID of the ALB instance. Valid values: true: uses the SLB-ID header. false (default): does not use the SLB-ID header. Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForSLBPortEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Port` header to retrieve the listener port of the ALB instance. Valid values: true: uses the X-Forwarded-Port header. false (default): does not use the X-Forwarded-Port header. Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForClientSourceIpsEnabled	boolean	No	Specifies whether to allow the ALB instance to retrieve client IP addresses from the `X-Forwarded-For` header. Valid values: true false (default) Note HTTP and HTTPS listeners support this parameter.	false
XForwardedForClientSourceIpsTrusted	string	No	The trusted proxy IP address. ALB traverses `X-Forwarded-For` backwards and selects the first IP address that is not in the trusted IP list as the originating IP address of the client, which will be throttled if source IP address throttling is enabled.	10.1.1.0/24
XForwardedForHostEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Host` header to retrieve the client domain name. Valid values: true false (default) Note This parameter is available for HTTP, HTTPS, and QUIC listeners.	false
QuicConfig	object	No	Select a QUIC listener and associate it with the ALB instance.
QuicListenerId	string	No	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 QUIC listener must be added to the same ALB instance. Make sure that the QUIC listener is not associated with any other listeners.	lsn-o4u54y73wq7b******
QuicUpgradeEnabled	boolean	No	Specifies whether to enable QUIC upgrade. Valid values: true: enables QUIC upgrade. false (default): disables QUIC upgrade. Note Only HTTPS listeners support this parameter.	false
Certificates	array<object>	No	The details about each certificate.
	object	No	The configurations of the certificate.
CertificateId	string	No	The ID of the certificate. Only server certificates are supported. You can specify up to 20 certificate IDs.	103705*******
CaCertificates	array<object>	No	The certificate authority (CA) certificates. You can specify only one CA certificate.
	object	No	The CA hierarchy.
CertificateId	string	No	The ID of the CA certificate. Note This parameter is required if CaEnabled is set to true.	123157*******
DefaultActions	array<object>	Yes	The actions of the forwarding rule.
	object	Yes
ForwardGroupConfig	object	Yes	The configuration of the forwarding action. You can specify at most 20 actions.
ServerGroupTuples	array<object>	Yes	The destination server group to which requests are forwarded.
	object	Yes
ServerGroupId	string	Yes	The ID of the server group to which requests are forwarded.	sgp-8ilqs4axp6******
Type	string	Yes	The action type. You can specify only one action type. Valid value: ForwardGroup: forwards requests to multiple Server groups.	ForwardGroup
Tag	array<object>	No	The tags.
	object	No
Key	string	No	The tag key. The tag key can be up to 128 characters in length and cannot start with `acs:` or `aliyun`. It cannot contain `http://` or `https://`.	env
Value	string	No	The tag value. The tag value can be up to 128 characters in length and cannot start with `acs:` or `aliyun`. It cannot contain `http://` or `https://`.	product

Response parameters

Parameter	Type	Description	Example
	object
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
ListenerId	string	The ID of the listener.	lsn-o4u54y73wq7b******
RequestId	string	The ID of the request.	CEF72CEB-54B6-4AE8-B225-F876*******

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "ListenerId": "lsn-o4u54y73wq7b******",
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876*******"
}

Error codes

HTTP status code	Error code	Error message	Description
400	ResourceAlreadyExist.Listener	The specified resource %s is already exist.	-
400	IncorrectStatus.LoadBalancer	The status of %s [%s] is incorrect.	-
400	IncorrectBusinessStatus.LoadBalancer	The business status of %s [%s] is incorrect.	The business status of %s [%s] is incorrect.
400	ResourceQuotaExceeded.LoadBalancerListenersNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s, usage %s/%s.
400	OperationDenied.CrossLoadBalancerQUICListener	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	ResourceAlreadyAssociated.Listener	The specified resource %s is already associated.	The specified resource %s is already associated.
400	ResourceQuotaExceeded.SecurityPolicyAttachedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	ResourceQuotaExceeded.ServerGroupAttachedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	-
400	ResourceQuotaExceeded.LoadBalancerServersNum	The quota of %s is exceeded for resource %s, usage %s/%s.	-
400	ResourceQuotaExceeded.ServerAddedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	-
400	Mismatch.VpcId	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	OperationDenied.ServerGroupProtocolNotSupport	The operation is not allowed because of ServerGroupProtocolNotSupport.	The operation is not allowed because the server group protocol is not supported.
400	OperationDenied.GRPCServerGroup	The operation is not allowed because of %s.	-
400	Mismatch.LoadBalancerEditionAndConnectionDrain	The %s and %s are mismatched.	The %s and %s are mismatched.
400	Mismatch.LoadBalancerEditionAndSlowStartEnable	The %s and %s are mismatched.	The %s and %s are mismatched.
400	InvalidParameter	Invalid parameter, please check the parameter input.	Invalid parameter, please check the parameter input.
403	Forbidden.SecurityPolicy	Authentication has failed for SecurityPolicy.	-
403	Forbidden.LoadBalancer	Authentication is failed for %s.	Authentication is failed for %s.
403	Forbidden.Listener	Authentication is failed for %s.	Authentication is failed for %s.
404	ResourceNotFound.LoadBalancer	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.ServerGroup	The specified resource %s is not found.	-
404	ResourceNotFound.SecurityPolicy	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.Listener	The specified resource %s is not found.	-
404	ResourceNotFound.Certificate	The specified resource %s is not found.	The specified resource %s is not found.

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-12-20	The Error code has changed	View Change Details
2024-09-03	The Error code has changed	View Change Details
2024-01-29	The Error code has changed	View Change Details
2024-01-29	The Error code has changed	View Change Details
2024-01-18	The Error code has changed	View Change Details
2023-11-06	The Error code has changed	View Change Details