All Products
Search

This Product

    Global Accelerator:CreateListener

    Document Center

    Global Accelerator:CreateListener

    Last Updated:Dec 14, 2025

    A listener monitors connection requests and distributes traffic to endpoints based on forwarding rules defined by a scheduling algorithm. You can call the CreateListener operation to create a listener for a Global Accelerator (GA) instance.

    Operation description

    Note the following when you call this operation:

    • CreateListener is an asynchronous operation. After you send a request, the system returns a listener ID and creates the listener in the background. You can call the DescribeListener operation to query the state of the listener.

      • If a listener is in the init state, the listener is being created. In this state, you can only query the listener. You cannot perform other operations.

      • If a listener is in the active state, the listener is created.

    • The CreateListener operation does not support creating listeners for the same GA instance concurrently.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ga:CreateListener

    create

    *Listener

    acs:ga:{#regionId}:{#accountId}:listener/*

    *Accelerator

    acs:ga:{#regionId}:{#accountId}:ga/{#acceleratorId}
    • ga:TLSVersion
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID of the GA instance. Set the value to cn-hangzhou.

    cn-hangzhou
    ClientToken

    string

    No

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

    Generate a value for this parameter from your client. Make sure that the value is unique among different requests. The ClientToken parameter can contain only ASCII characters.

    Note

    If you do not specify this parameter, the system automatically uses the RequestId of the request as the ClientToken. The RequestId may be different for each request.

    123e4567-e89b-12d3-a456-426655440000

    AcceleratorId

    string

    Yes

    The ID of the GA instance.

    ga-bp1odcab8tmno0hdq****
    Name

    string

    No

    The name of the listener.

    The name must be 1 to 128 characters in length. It must start with a letter or a Chinese character and can contain digits, periods (.), underscores (_), and hyphens (-).

    Listener
    Description

    string

    No

    The description of the listener.

    The description can be up to 200 characters in length and cannot start with http:// or https://.

    Listener
    ClientAffinity

    string

    No

    The client affinity for the listener.

    • If you do not set this parameter, client affinity is disabled. This means that requests from the same client may be directed to different endpoints.

    • Set the value to SOURCE_IP. This enables client affinity. When a client accesses a stateful application, all requests from the same client are directed to the same endpoint, regardless of the source port or protocol.

    SOURCE_IP
    Protocol

    string

    No

    The network transmission protocol of the listener. Valid values:

    • tcp: TCP.

    • udp: UDP.

    • http: HTTP.

    • https: HTTPS.

    tcp
    PortRanges

    array<object>

    Yes

    The listener port. The valid port range is 1 to 65499. The number of ports that you can create depends on the routing type and protocol of the listener. For more information, see Listener ports.

    object

    No

    The listener port.

    The valid port range is 1 to 65499.

    The number of ports that you can create depends on the routing type and protocol of the listener. For more information, see Listener ports.

    FromPort

    integer

    Yes

    The first port of the listener port range that is used to receive and forward requests to endpoints.

    The valid port range is 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    The number of ports that you can create depends on the routing type and protocol of the listener. For more information, see Listener ports.

    Note

    For HTTP or HTTPS listeners, you can specify only one listener port. The start port and the end port must be the same.

    20
    ToPort

    integer

    Yes

    The last port of the listener port range that is used to receive and forward requests to endpoints.

    The valid port range is 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    The number of ports that you can create depends on the routing type and protocol of the listener. For more information, see Listener ports.

    Note

    For HTTP or HTTPS listeners, you can specify only one listener port. The start port and the end port must be the same.

    20
    Certificates

    array<object>

    No

    The list of SSL certificates.

    object

    No

    The list of SSL certificates.

    Id

    string

    No

    The ID of the SSL certificate.

    Note

    This parameter is required only for HTTPS listeners.

    449****-cn-hangzhou
    XForwardedForConfig

    object

    No

    The configuration of the XForward field.

    XForwardedForGaIdEnabled

    boolean

    No

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

    • true: yes.

    • false (default): no.

    Note

    This parameter is supported only by HTTP and HTTPS listeners.

    false
    XForwardedForGaApEnabled

    boolean

    No

    Specifies whether to use the GA-AP header to retrieve information about the acceleration region. Valid values:

    • true: yes.

    • false (default): no.

    Note

    This parameter is supported only by HTTP and HTTPS listeners.

    false
    XForwardedForProtoEnabled

    boolean

    No

    Specifies whether to use the GA-X-Forward-Proto header to retrieve the listener protocol of the GA instance. Valid values:

    • true: yes.

    • false (default): no.

    Note

    This parameter is supported only by HTTP and HTTPS listeners.

    false
    XForwardedForPortEnabled

    boolean

    No

    Specifies whether to use the GA-X-Forward-Port header to retrieve the listener port of the GA instance. Valid values:

    • true: yes.

    • false (default): no.

    Note

    This parameter is supported only by HTTP and HTTPS listeners.

    false
    XRealIpEnabled

    boolean

    No

    Specifies whether to use the X-Real-IP header to retrieve the real IP address of the client. Valid values:

    • true: yes.

    • false (default): no.

    Note

    This parameter is supported only by HTTP and HTTPS listeners.

    false
    SecurityPolicyId

    string

    No

    The ID of the security policy. Valid values:

    • tls_cipher_policy_1_0

      • Supported TLS versions: TLSv1.0, TLSv1.1, and TLSv1.2.

      • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_1

      • Supported TLS versions: TLSv1.1 and TLSv1.2.

      • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_2

      • Supported TLS version: TLSv1.2.

      • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.

    • tls_cipher_policy_1_2_strict

      • Supported TLS version: TLSv1.2.

      • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.

    • tls_cipher_policy_1_2_strict_with_1_3

      • Supported TLS versions: TLSv1.2 and TLSv1.3.

      • Supported cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_AES_128_CCM_8_SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-SHA256, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES128-SHA, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.

    Note

    This parameter is supported only by HTTPS listeners.

    tls_cipher_policy_1_0
    Type

    string

    No

    The routing type of the listener. Valid values:

    • Standard (default): smart routing.

    • CustomRouting: custom routing.

    Note

    • The custom routing feature is in invitational preview. To use this feature, contact your Alibaba Cloud account manager.

    • You cannot create listeners of different routing types in the same standard GA instance. After a routing type is specified, you cannot change it. For more information, see Listener overview.

    Standard
    EndpointGroupConfigurations

    array<object>

    No

    The configurations of the endpoint group that is associated with the smart routing listener.

    You can configure up to 10 endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    array<object>

    No

    The configurations of the endpoint group that is associated with the smart routing listener.

    You can configure up to 10 endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    EndpointGroupName

    string

    No

    The name of the endpoint group that is associated with the smart routing listener.

    The name must be 1 to 128 characters in length. It must start with a letter or a Chinese character and can contain digits, periods (.), underscores (_), and hyphens (-).

    You can specify up to 10 endpoint group names.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    test
    EndpointGroupDescription

    string

    No

    The description of the endpoint group that is associated with the smart routing listener.

    The description can be up to 200 characters in length and cannot start with http:// or https://.

    You can specify up to 10 endpoint group descriptions.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    test
    EndpointGroupRegion

    string

    No

    The ID of the region where the endpoint group of the smart routing listener is deployed.

    You can specify up to 10 region IDs.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    cn-hangzhou
    TrafficPercentage

    integer

    No

    The traffic percentage that is allocated to the endpoint group of the smart routing listener. If a listener is associated with multiple endpoint groups, this parameter specifies the percentage of traffic that is distributed to each endpoint group.

    The value must be an integer from 1 to 100. The default value is 100.

    You can specify traffic percentages for up to 10 endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    100
    HealthCheckEnabled

    boolean

    No

    Specifies whether to enable the health check feature for the endpoint group of the smart routing listener. Valid values:

    • true: enables the health check feature.

    • false (default): disables the health check feature.

    You can enable the health check feature for up to 10 endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    false
    HealthCheckIntervalSeconds

    integer

    No

    The interval at which health checks are performed. Unit: seconds.

    You can specify up to 10 health check intervals.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    3
    HealthCheckPath

    string

    No

    The path to which health check requests are sent.

    You can specify up to 10 health check paths.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    /healthcheck
    HealthCheckPort

    integer

    No

    The port that is used for health checks. The valid port range is 1 to 65535.

    You can specify up to 10 health check ports.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    20
    HealthCheckProtocol

    string

    No

    The protocol that is used for health checks. Valid values:

    • tcp or TCP: TCP.

    • http or HTTP: HTTP.

    • https or HTTPS: HTTPS.

    You can specify up to 10 health check protocols.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    tcp
    ThresholdCount

    integer

    No

    The number of consecutive health checks that an endpoint must pass or fail. An endpoint is considered healthy after it passes the specified number of consecutive health checks. An endpoint is considered unhealthy after it fails the specified number of consecutive health checks. The value must be an integer from 2 to 10. The default value is 3.

    You can specify up to 10 values for this parameter.

    Note

    This parameter is available only when the Type of the listener is set to Standard.

    3
    EndpointConfigurations

    array<object>

    No

    The configurations of the endpoint that is associated with the smart routing listener.

    object

    No

    The configurations of the endpoint that is associated with the smart routing listener.

    Type

    string

    No

    The type of the endpoint that is associated with the smart routing listener. Valid values:

    • Domain: a custom domain name.

    • Ip: a custom IP address.

    • PublicIp: an Alibaba Cloud public IP address.

    • ECS: an Alibaba Cloud Elastic Compute Service (ECS) instance.

    • SLB: an Alibaba Cloud Server Load Balancer (SLB) instance.

    • ALB: an Alibaba Cloud Application Load Balancer (ALB) instance.

    • OSS: an Alibaba Cloud Object Storage Service (OSS) bucket.

    • ENI: an Alibaba Cloud elastic network interface (ENI).

    • NLB: an Alibaba Cloud Network Load Balancer (NLB) instance.

    • IpTarget: a custom private IP address.

    You can specify up to 100 endpoint types for an endpoint group of a smart routing listener.

    Note

    • This parameter is required when the Type of the listener is set to Standard.

    • If the endpoint type is ECS, ENI, SLB, ALB, NLB, or IpTarget, and the service-linked role AliyunServiceRoleForGaVpcEndpoint does not exist, the system automatically creates the service-linked role.

    • If the endpoint type is ALB, and the service-linked role AliyunServiceRoleForGaAlb does not exist, the system automatically creates the service-linked role.

    • If the endpoint type is OSS, and the service-linked role AliyunServiceRoleForGaOss does not exist, the system automatically creates the service-linked role.

    • If the endpoint type is NLB, and the service-linked role AliyunServiceRoleForGaNlb does not exist, the system automatically creates the service-linked role.

    Note

    For more information, see Service-linked roles.

    Ip
    Weight

    integer

    No

    The weight of the endpoint that is associated with the smart routing listener.

    The value must be an integer from 0 to 255.

    You can specify the weights of up to 100 endpoints in an endpoint group.

    Note

    • This parameter is required when the Type of the listener is set to Standard.

    • If you set the weight of an endpoint to 0, GA stops distributing traffic to the endpoint. Proceed with caution.

    20
    Endpoint

    string

    No

    The IP address or domain name of the endpoint that is associated with the smart routing listener.

    You can specify up to 100 IP addresses or domain names in an endpoint group.

    Note

    This parameter is required when the Type of the listener is set to Standard.

    47.0.XX.XX
    SubAddress

    string

    No

    The private IP address of the ENI.

    Note

    This parameter is available only when the endpoint type is ENI. If you do not specify this parameter, the primary private IP address of the ENI is used.

    172.168.XX.XX
    EnableClientIPPreservation

    boolean

    No

    Specifies whether to preserve the IP addresses of clients. Valid values:

    • true: preserves the IP addresses of clients.

    • false (default): does not preserve the IP addresses of clients.

    Note

    • By default, client IP address preservation is disabled for endpoint groups of UDP and TCP listeners. You can enable this feature as needed.

    • By default, client IP address preservation is enabled for endpoint groups of HTTP and HTTPS listeners. The client IP addresses are retrieved from the X-Forwarded-For header. You cannot disable this feature.

    • You cannot set both EnableClientIPPreservation and EnableProxyProtocol to true.

    • For more information, see Preserve client IP addresses.

    EnableProxyProtocol

    boolean

    No

    Specifies whether to use the Proxy protocol to preserve the IP addresses of clients. Valid values:

    • true: uses the Proxy protocol.

    • false (default): does not use the Proxy protocol.

    Note

    • This parameter is available only for endpoint groups of TCP listeners.

    • You cannot set both EnableClientIPPreservation and EnableProxyProtocol to true.

    • For more information, see Preserve client IP addresses.

    VpcId

    string

    No

    The ID of the VPC.

    You can specify only one VPC ID for an endpoint group of a smart routing listener.

    Note

    This parameter is required and takes effect only when the endpoint type is IpTarget.

    vpc-bp13r1kpr2lel****
    VSwitchIds

    array

    No

    The list of vSwitches in the VPC.

    string

    No

    The ID of the vSwitch.

    You can specify up to two vSwitch IDs for an endpoint group of a smart routing listener.

    Note

    This parameter is required and takes effect only when the endpoint type is IpTarget.

    • The vSwitch must belong to the VPC that is specified by the VpcId parameter.

    vsw-0jlhcznhw5m7pz2fa****
    EndpointRequestProtocol

    string

    No

    The protocol of the backend service. Valid values:

    • HTTP (default): HTTP.

    • HTTPS: HTTPS.

    You can specify up to 10 backend service protocols.

    Note

    • This parameter is available only when the Type of the listener is set to Standard.

    • You can specify this parameter only when you create an endpoint group for an HTTP or HTTPS listener.

    • For HTTP listeners, only HTTP is supported.

    HTTP
    EndpointProtocolVersion

    string

    No

    The version of the backend service protocol. Valid values:

    • HTTP1.1 (default): HTTP/1.1.

    • HTTP2: HTTP/2.

    Note

    This parameter is available only when EndpointRequestProtocol is set to HTTPS.

    EndpointGroupType

    string

    No

    The type of the endpoint group that is associated with the smart routing listener. Valid values:

    • default (default): a default endpoint group.

    • virtual: a virtual endpoint group.

    You can specify up to 10 endpoint group types.

    Note

    • This parameter is available only when the Type of the listener is set to Standard.

    • You can create a virtual endpoint group only for an HTTP or HTTPS listener.

    default
    PortOverrides

    array<object>

    No

    The port mapping.

    object

    No

    The port mapping.

    ListenerPort

    integer

    No

    The listener port that is used for the port mapping.

    You can specify up to five listener ports for port mappings.

    Note

    • This parameter is available only when the Type of the listener is set to Standard.

    • For TCP listeners, virtual endpoint groups do not support port mappings. If a listener is associated with a virtual endpoint group, you cannot configure port mappings for the default endpoint group. If you configure port mappings for the default endpoint group, you cannot add a virtual endpoint group.

    • After you configure a port mapping, you cannot change the listener protocol, except for changing the protocol from HTTP to HTTPS, or from HTTPS to HTTP.

    • The listener port range that you specify must include all listener ports that are used for port mappings. For example, if the listener port range is 80-82 and you configure a port mapping for listener ports 100-102, you cannot change the listener port range to 80-81.

    443
    EndpointPort

    integer

    No

    The endpoint port that is used for the port mapping.

    You can specify up to five endpoint ports for port mappings.

    Note

    • This parameter is available only when the Type of the listener is set to Standard.

    • For TCP listeners, virtual endpoint groups do not support port mappings. If a listener is associated with a virtual endpoint group, you cannot configure port mappings for the default endpoint group. If you configure port mappings for the default endpoint group, you cannot add a virtual endpoint group.

    • After you configure a port mapping, you cannot change the listener protocol, except for changing the protocol from HTTP to HTTPS, or from HTTPS to HTTP.

    • The listener port range that you specify must include all listener ports that are used for port mappings. For example, if the listener port range is 80-82 and you configure a port mapping for listener ports 100-102, you cannot change the listener port range to 80-81.

    80
    HealthCheckHost

    string

    No

    CustomRoutingEndpointGroupConfigurations

    array<object>

    No

    The configurations of the endpoint group that is associated with the custom routing listener.

    You can configure up to five endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    array<object>

    No

    The configurations of the endpoint group that is associated with the custom routing listener.

    You can configure up to five endpoint groups.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    EndpointGroupRegion

    string

    No

    The ID of the region where the endpoint group of the custom routing listener is deployed.

    You can specify up to five region IDs.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    cn-hangzhou
    Name

    string

    No

    The name of the endpoint group that is associated with the custom routing listener.

    The name must be 1 to 128 characters in length. It must start with a letter or a Chinese character and can contain digits, periods (.), underscores (_), and hyphens (-).

    You can specify up to five endpoint group names.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    test
    Description

    string

    No

    The description of the endpoint group that is associated with the custom routing listener.

    The description can be up to 200 characters in length and cannot start with http:// or https://.

    You can specify up to five endpoint group descriptions.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    test
    DestinationConfigurations

    array<object>

    No

    The mapping configurations of the endpoint group that is associated with the custom routing listener.

    You must specify the backend service port range and protocol. The settings are mapped to the listener port range.

    You can specify up to 20 mapping configurations for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    object

    No

    The mapping configurations of the endpoint group that is associated with the custom routing listener.

    You must specify the backend service port range and protocol. The settings are mapped to the listener port range.

    You can specify up to 20 mapping configurations for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    Protocols

    array

    No

    The protocol of the backend service.

    You can specify up to four backend service protocols for each mapping configuration of an endpoint group.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    string

    No

    The protocol of the backend service. Valid values:

    • TCP: TCP.

    • UDP: UDP.

    • TCP,UDP: TCP and UDP.

    You can specify up to four backend service protocols for each mapping configuration of an endpoint group.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    TCP
    FromPort

    integer

    No

    The first port of the backend service port range of the endpoint group.

    The valid port range is 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    You can specify up to 20 first ports for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    80
    ToPort

    integer

    No

    The last port of the backend service port range of the endpoint group.

    The valid port range is 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    You can specify up to 20 last ports for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    80
    EndpointConfigurations

    array<object>

    No

    The configurations of the endpoint that is associated with the custom routing listener.

    You can specify up to 10 endpoints for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    array<object>

    No

    The configurations of the endpoint that is associated with the custom routing listener.

    You can specify up to 10 endpoints for each endpoint group of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    Type

    string

    No

    The type of the backend service. Valid value:

    PrivateSubNet (default): a private CIDR block.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    PrivateSubNet
    Endpoint

    string

    No

    The name of the vSwitch instance.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    vsw-test01
    TrafficToEndpointPolicy

    string

    No

    The traffic policy for the backend service. Valid values:

    • DenyAll (default): denies all traffic to the backend service.

    • AllowAll: allows all traffic to the backend service.

    • AllowCustom: allows traffic only from specified IP addresses to the backend service. You must specify the IP addresses and port ranges. If you do not specify a port range, all ports are supported.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    DenyAll
    PolicyConfigurations

    array<object>

    No

    The configurations of the traffic policy.

    You can specify up to 20 traffic policies for each endpoint of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    array<object>

    No

    The configurations of the traffic policy.

    You can specify up to 20 traffic policies for each endpoint of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    Address

    string

    No

    The IP address of the traffic destination.

    This parameter takes effect only when TrafficToEndpointPolicy is set to AllowCustom.

    You can specify up to 20 destination IP addresses for each endpoint of a custom routing listener.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    10.0.XX.XX
    PortRanges

    array<object>

    No

    The port range of the traffic destination. The port range must be within the backend service port range of the endpoint group.

    If you do not specify this parameter, all ports are supported.

    This parameter takes effect only when TrafficToEndpointPolicy is set to AllowCustom.

    You can specify up to 20 port ranges for each endpoint of a custom routing listener. You can specify up to five port ranges for each traffic destination.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    object

    No

    The port range of the traffic destination. The port range must be within the backend service port range of the endpoint group.

    If you do not specify this parameter, all ports are supported.

    This parameter takes effect only when TrafficToEndpointPolicy is set to AllowCustom.

    You can specify up to 20 port ranges for each endpoint of a custom routing listener. You can specify up to five port ranges for each traffic destination.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    FromPort

    integer

    No

    The first port of the destination port range. The port must be within the backend service port range of the endpoint group.

    This parameter takes effect only when TrafficToEndpointPolicy is set to AllowCustom.

    You can specify up to 20 port ranges for each endpoint of a custom routing listener. You can specify up to five first ports for each traffic destination.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    80
    ToPort

    integer

    No

    The last port of the destination port range. The port must be within the backend service port range of the endpoint group.

    This parameter takes effect only when TrafficToEndpointPolicy is set to AllowCustom.

    You can specify up to 20 port ranges for each endpoint of a custom routing listener. You can specify up to five last ports for each traffic destination.

    Note

    This parameter is available only when the Type of the listener is set to CustomRouting.

    80
    IdleTimeout

    integer

    No

    The timeout period of idle connections. Unit: seconds.

    • TCP: 10 to 900. Default value: 900.

    • UDP: 10 to 20. Default value: 20.

    • HTTP/HTTPS: 1 to 60. Default value: 15.

    900
    RequestTimeout

    integer

    No

    The timeout period for HTTP or HTTPS requests. Unit: seconds.

    Valid values: 1 to 180. Default value: 60.

    Note

    This parameter is valid only for HTTP or HTTPS listeners. If a backend server does not respond within the timeout period, GA returns an HTTP 504 error to the client.

    15
    HttpVersion

    string

    No

    The maximum version of the HTTP protocol. Valid values:

    • http3: HTTP/3.

    • http2 (default): HTTP/2.

    • http1.1: HTTP/1.1.

    Note

    This parameter is supported only by HTTPS listeners.

    http2

    Response elements

    Element

    Type

    Description

    Example

    object

    The returned data.

    RequestId

    string

    The request ID.

    04F0F334-1335-436C-A1D7-6C044FE73368
    ListenerId

    string

    The ID of the listener.

    lsr-bp1bpn0kn908w4nbw****

    Examples

    Success response

    JSON format

    {
  "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368",
  "ListenerId": "lsr-bp1bpn0kn908w4nbw****"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 Resource.QuotaFull The resource quota is exceeded. The number of resources has reached the upper limit.
    400 ProtocalIllegal.Listener The specified listener protocol is invalid. The specified listener protocol is invalid.
    400 NotExist.Accelerator The accelerated instance does not exist. The GA instance does not exist.
    400 StateError.Accelerator The state of the accelerated instance is invalid. The status of the GA instance is invalid.
    400 QuotaExceeded.Listener The maximum number of listeners is exceeded. The maximum number of listeners is exceeded.
    400 QuotaExceeded.ListenerPort The maximum number of listener ports is exceeded. The maximum number of listener ports is exceeded.
    400 NotExist.ListenerPort listener port %s is not exist
    400 PortRangeIllegal.Listener The specified listener port range is invalid. The specified listener port range is invalid.
    400 PortRangeIllegal.Count The hugePort listener only supports one port range. The mass port listener (port number greater than 300) only supports one port range.
    400 PortConflict.Listener The listener port configuration is in conflict. The listener port configurations are in conflict.
    400 PortRangeIllegal.ExceedGaAbility The listener port range is invalid. For each accelerator instance, you can only create a listener with port range over 300 for each protocol (TCP and UDP). The listener port range is invalid. For each accelerator instance, you can only create a listener with port range over 300 for each protocol (TCP and UDP).
    400 PortRangeIllegal.UDP UDP ports 250, 4789, and 4790 are system reserved ports.
    400 SystemPort.Listener Ports 65500-65535 are system reserved ports. Ports 65500 to 65535 are reserved by the system.
    400 PortRanges.MustOne The portRanges must be one for HTTPS and HTTP type listener. Only one port is supported for HTTPS and HTTP type listeners.
    400 SecurityPolicyId.NotNeed No security policy ID is required for the listener. No security policy ID is required for the listener.
    400 SecurityPolicyIdIllegal.Listener The listener security policy ID %s is illegal. The security policy ID of the listener is invalid.
    500 UnknownError An error occurred while processing your request. Please try again. If the error persists, please submit a ticket. An error occurred while the request was being processed. Try again later.
    403 Forbbiden.SubUser You are not authorized to operate on the specified resource because your account was created by another user. The current account is a RAM user and does not have permissions to manage the specified resources.
    403 Forbidden The user is not authorized to operate on the specified resource. The current account does not have permissions to manage the specified resources.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.