All Products
Search

This Product

    Global Accelerator:UpdateListener

    Document Center

    Global Accelerator:UpdateListener

    Last Updated:Apr 10, 2024

    Modifies a specified listener of a Global Accelerator (GA) instance.

    Operation description

    This operation can be called to modify the configurations such as the protocol and ports of a listener to meet your business requirements.

    When you call this operation, take note of the following items:

    • UpdateListener is an asynchronous operation. After you send a request, the system returns a request ID and runs the task in the background. You can call the DescribeListener operation to query the status of a listener.

      • If the listener is in the updating state, it indicates that its configurations are being modified. In this case, you can perform only query operations.
      • If the listener is in the active state, it indicates that its configurations are modified.

    • The UpdateListener operation cannot be repeatedly called to modify listener configurations for the same GA instance within a specific period of time.

    Debugging

    OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

    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.
    OperationAccess levelResource typeCondition keyAssociated operation
    ga:UpdateListenerWrite
    • Listener
      acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    RegionIdstringNo

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

    		cn-hangzhou
    ClientTokenstringNo

    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 the value is unique among different requests. The ClientToken value can contain only ASCII characters.

    Note If you do not set this parameter, ClientToken is set to the value of RequestId. The value of RequestId for each API request may be different.
    		123e4567-e89b-12d3-a456-426655440000
    NamestringNo

    The name of the listener.

    The name must be 2 to 128 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter.

    		Listener
    DescriptionstringNo

    The description of the listener. The description can be at most 200 characters in length.

    		Listener
    ClientAffinitystringNo

    Specifies whether to enable client affinity for the listener.

    • If this parameter is left empty, client affinity is disabled. After client affinity is disabled, requests from a specific client IP address may be forwarded to different endpoints.
    • To enable client affinity, set this parameter to SOURCE_IP. In this case, when a client accesses stateful applications, requests from the same client are always forwarded to the same endpoint regardless of the source port or protocol.
    		SOURCE_IP
    ProtocolstringNo

    The network transmission protocol that is used by the listener. Valid values:

    • tcp: TCP
    • udp: UDP
    • http: HTTP
    • https: HTTPS
    		tcp
    ListenerIdstringYes

    The ID of the listener.

    		lsr-bp1bpn0kn908w4nbw****
    ProxyProtocolstringNo

    Specifies whether to reserve client IP addresses. Default value: false. Valid values:

    • true: enables client IP preservation. After client IP addresses are reserved, you can view client IP addresses on the endpoints.
    • false (default): disables client IP preservation.
    Note This parameter will be deprecated in the API operations that are used to configure listeners. We recommend that you set this parameter when you call API operations to configure endpoint groups. For more information about the ProxyProtocol parameter, see CreateEndpointGroup and UpdateEndpointGroup .
    		false
    PortRangesobject []No

    The listener ports that are used to receive requests and forward the requests to endpoints.

    Valid values: 1 to 65499.

    The maximum number of ports that can be configured varies based on the routing type and protocol of the listener. For more information, see Listener overview.

    FromPortintegerYes

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

    Valid values: 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    The maximum number of ports that can be configured varies based on the routing type and protocol of the listener. For more information, see Listener overview.

    Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the first port is the same as the last port.
    		20
    ToPortintegerYes

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

    Valid values: 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

    The maximum number of ports that can be configured varies based on the routing type and protocol of the listener. For more information, see Listener overview.

    Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the first port is the same as the last port.
    		21
    Certificatesobject []No

    The SSL certificate.

    IdstringNo

    The ID of the SSL certificate.

    Note This parameter is required only when you configure an HTTPS listener.
    		449****-cn-hangzhou
    BackendPortsobject []No

    The range of ports that are used by backend servers to receive requests.

    FromPortintegerNo

    The first port in the range of ports that are used by backend servers to receive requests.

    Note This parameter is required only when you configure an HTTPS or HTTP listener and the listener port is different from the service port of the backend servers. In this case, the first port that is used by the backend servers to receive requests must be the same as the last port.
    		80
    ToPortintegerNo

    The last port in the range of ports that are used by backend servers to receive requests.

    Note This parameter is required only when you configure an HTTPS or HTTP listener and the listener port is different from the service port of the backend servers. In this case, the first port that is used by the backend servers to receive requests must be the same as the last port.
    		80
    XForwardedForConfigobjectNo

    The XForward headers.

    XForwardedForGaIdEnabledbooleanNo

    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 available only when you create an HTTPS or HTTP listener.
    		false
    XForwardedForProtoEnabledbooleanNo

    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 available only when you create an HTTPS or HTTP listener.
    		false
    XForwardedForPortEnabledbooleanNo

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

    • true: yes
    • false (default): no
    Note This parameter is available only when you create an HTTPS or HTTP listener.
    		false
    XRealIpEnabledbooleanNo

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

    • true: yes
    • false (default): no
    Note This parameter is available only when you create an HTTPS or HTTP listener.
    		false
    XForwardedForGaApEnabledbooleanNo

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

    • true: yes
    • false (default): no
    Note This parameter is available only when you create an HTTPS or HTTP listener.
    		false
    SecurityPolicyIdstringNo

    The ID of the security policy. Valid values:

    • tls_cipher_policy_1_0

      • Supported Transport Layer Security (TLS) versions: TLS 1.0, TLS 1.1, and TLS 1.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: TLS 1.1 and TLS 1.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: TLS 1.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: TLS 1.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: TLS 1.2 and TLS 1.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 available only when you create an HTTPS listener.
    		tls_cipher_policy_1_0
    IdleTimeoutintegerNo

    The timeout period for idle connections. Unit: seconds.

    • TCP: 10-900. Default value: 900. Unit: seconds.
    • UDP: 10-20. Default value: 20. Unit: seconds.
    • HTTP/HTTPS: 1-60. Default value: 15. Unit: seconds.
    		900
    RequestTimeoutintegerNo

    The timeout period for HTTP or HTTPS requests.

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

    Note This parameter takes effect only for HTTP or HTTPS listeners. If the backend server does not respond within the timeout period, GA returns an HTTP 504 error code to the client.
    		60
    HttpVersionstringNo

    The maximum version of the HTTP protocol. Valid values:

    • http3
    • http2
    • http1.1
    Note Only HTTPS listeners support this parameter.
    		http2

    Response parameters

    ParameterTypeDescriptionExample
    object

    The returned information.

    RequestIdstring

    The ID of the request.

    		6FEA0CF3-D3B9-43E5-A304-D217037876A8

    Examples

    Sample success responses

    JSONformat

    {
  "RequestId": "6FEA0CF3-D3B9-43E5-A304-D217037876A8\t"
}

    Error codes

    HTTP status codeError codeError messageDescription
    400NotActive.ListenerThe state of the listener is not active.The listener is unstable.
    400PortRangeIllegal.ListenerThe specified listener port range is invalid.The specified listener port range is invalid.
    400PortConflict.ListenerThe listener port configuration is in conflict.The listener port configurations are in conflict.
    400QuotaExceeded.ListenerPortThe maximum number of listener ports is exceeded.The maximum number of listener ports is exceeded.
    400NotExist.AcceleratorThe accelerated instance does not exist.The GA instance does not exist.
    400StateError.AcceleratorThe state of the accelerated instance is invalid.The status of the GA instance is invalid.
    400Exist.PortOverridePort override exists.The port mapping already exists.
    400RegionNotSupportHugePort.ListenerThe current ipSet or listener region does not support hugePort.-
    400PortRanges.MustOneThe portRanges must be one for HTTPS and HTTP type listener.Only one port is supported for HTTPS and HTTP type listeners.
    400SecurityPolicyIdIllegal.ListenerThe listener security policy ID %s is illegal.The security policy ID of the listener is invalid.
    400SecurityPolicyId.NotNeedNo security policy ID is required for the listener.No security policy ID is required for the listener.
    403Forbbiden.SubUserYou 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.
    403ForbiddenThe user is not authorized to operate on the specified resource.The current account does not have permissions to manage the specified resources.
    500UnknownErrorAn 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.

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

    Change history

    Change timeSummary of changesOperation
    2024-03-27The Error code has changed. The request parameters of the API has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      delete Error Codes: 400
      delete Error Codes: 403
      delete Error Codes: 500
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: HttpVersion
    2023-11-06The Error code has changed. The request parameters of the API has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      delete Error Codes: 400
      delete Error Codes: 403
      delete Error Codes: 500
    Input ParametersThe request parameters of the API has changed.
      Added Input Parameters: IdleTimeout
      Added Input Parameters: RequestTimeout