Creates an HTTP, HTTPS, or QUIC listener in a region.
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
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:
- The required resource types are displayed in bold characters.
- 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 | Write |
|
| 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:
| 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 | 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
| true |
Http2Enabled | boolean | No | Specifies whether to enable
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:
| false |
XForwardedForConfig | object | No | ||
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
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
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
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
Note
Only HTTPS listeners support this parameter.
| true |
XForwardedForClientSrcPortEnabled | boolean | No | Specifies whether to use the
Note
HTTP and HTTPS listeners support this parameter.
| true |
XForwardedForEnabled | boolean | No | Specifies whether to use the
Note
HTTP and HTTPS listeners support this parameter.
| true |
XForwardedForProtoEnabled | boolean | No | Specifies whether to use the
Note
HTTP, HTTPS, and QUIC listeners support this parameter.
| false |
XForwardedForSLBIdEnabled | boolean | No | Specifies whether to use the
Note
HTTP, HTTPS, and QUIC listeners support this parameter.
| false |
XForwardedForSLBPortEnabled | boolean | No | Specifies whether to use the
Note
HTTP, HTTPS, and QUIC listeners support this parameter.
| false |
XForwardedForClientSourceIpsEnabled | boolean | No | Specifies whether to use the
Note
HTTP, HTTPS, and QUIC listeners support this parameter. The feature corresponding to this parameter is not available by default. If you want to use this feature, submit a ticket.
| false |
XForwardedForClientSourceIpsTrusted | string | No | The trusted proxy IP address. ALB traverses | 10.1.1.0/24 |
QuicConfig | object | No | ||
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.
| lsr-bp1bpn0kn908w4nbw**** |
QuicUpgradeEnabled | boolean | No | Specifies whether to enable QUIC upgrade. Valid values:
Note
Only HTTPS listeners support this parameter.
| false |
Certificates | object [] | No | ||
CertificateId | string | No | The ID of the certificate. Only server certificates are supported. You can specify up to 20 certificate IDs. | 12315790212_166f8204689_1714763408_70998**** |
DefaultActions | object [] | Yes | ||
ForwardGroupConfig | object | Yes | ||
ServerGroupTuples | object [] | Yes | ||
ServerGroupId | string | Yes | The ID of the server group to which requests are forwarded. | rsp-cige6j**** |
Type | string | Yes | The action type. You can specify only one action type. Valid value: ForwardGroup: forwards requests to multiple vServer groups. | ForwardGroup |
Tag | object [] | No | The tags. | |
Key | string | No | The tag key. The tag key can be up to 128 characters in length and cannot start with | env |
Value | string | No | The tag value. The tag value can be up to 128 characters in length and cannot start with | product |
Response parameters
Examples
Sample success responses
JSON
format
{
"JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
"ListenerId": "lsr-bp1bpn0kn908w4nbw****",
"RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984"
}
Error codes
HTTP status code | Error code | Error message | Description |
---|---|---|---|
400 | ResourceAlreadyExist.Listener | The specified resource %s is already exist. | The specified resource %s already exists. |
400 | IncorrectStatus.LoadBalancer | The status of %s [%s] is incorrect. | 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. | 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. | 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. | 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. |
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. | 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. | 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-01-29 | The Error code has changed | see changesets | ||||||||
| ||||||||||
2024-01-29 | The Error code has changed | see changesets | ||||||||
| ||||||||||
2024-01-18 | The Error code has changed | see changesets | ||||||||
| ||||||||||
2023-11-06 | The Error code has changed | see changesets | ||||||||
|