Help Center/ Global Accelerator/ API Reference/ API/ Listener/ Updating a Listener

Updated on 2024-11-11 GMT+08:00

Online Debugging

CLI Examples

View PDF

Updating a Listener

Function

This API is used to update a listener.

Calling Method

For details, see Calling APIs.

URI

PUT /v1/listeners/{listener_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
listener_id	Yes	String	Specifies the listener ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Specifies the user token. The token can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
listener	Yes	UpdateListenerOption object	Specifies the detailed information about updating a listener.

**Table 4** UpdateListenerOption
Parameter	Mandatory	Type	Description
name	No	String	Specifies the listener name. The name can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.
description	No	String	Specifies the information about the listener. The value can contain 0 to 255 characters. The following characters are not allowed: <>
port_ranges	No	Array of PortRange objects	Specifies the port range used by the listener.
client_affinity	No	String	Specifies the client affinity. The value can be one of the following: Source IP address: Requests from the same IP address are forwarded to the same endpoint. NONE: Requests are evenly forwarded across the endpoints.

**Table 5** PortRange
Parameter	Mandatory	Type	Description
from_port	Yes	Integer	Specifies the start port number.
to_port	Yes	Integer	Specifies the end port number.

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
listener	ListenerDetail object	Specifies the detail of a listener.
request_id	String	Specifies the request ID.

**Table 7** ListenerDetail
Parameter	Type	Description
id	String	Specifies the listener ID.
name	String	Specifies the listener name. The name can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.
description	String	Specifies the information about the listener. The value can contain 0 to 255 characters. The following characters are not allowed: <>
protocol	String	Specifies the protocol used by the listener to forward requests.
status	String	Specifies the provisioning status. The value can be one of the following: ACTIVE: The resource is running. PENDING: The status is to be determined. ERROR: Failed to create the resource. DELETING: The resource is being deleted.
port_ranges	Array of PortRange objects	Specifies the port range used by the listener.
client_affinity	String	Specifies the client affinity. The value can be one of the following: Source IP address: Requests from the same IP address are forwarded to the same endpoint. NONE: Requests are evenly forwarded across the endpoints.
accelerator_id	String	Specifies the ID of the global accelerator associated with the listener.
created_at	String	Specifies when the listener was added.
updated_at	String	Specifies when the listener was updated.
domain_id	String	Specifies the tenant ID.
frozen_info	FrozenInfo object	Specifies the frozen details of cloud services or resources.
tags	Array of ResourceTag objects	Specifies the tags.

**Table 8** PortRange
Parameter	Type	Description
from_port	Integer	Specifies the start port number.
to_port	Integer	Specifies the end port number.

**Table 9** FrozenInfo
Parameter	Type	Description
status	Integer	Specifies the status of a cloud service or resource. The value can be one of the following: 0: unfrozen/normal (The cloud service will recover after being unfrozen.) 1: frozen (Resources and data will be retained, but the cloud service cannot be used.) 2: deleted/terminated (Both resources and data will be cleared.)
effect	Integer	Specifies the status of the resource after being frozen. The value can be one of the following: 1 (default): The resource is frozen and can be released. 2: The resource is frozen and cannot be released. 3: The resource is frozen and cannot be renewed.
scene	Array of strings	Specifies the service scenario. The value can be one of the following: ARREAR: The cloud service is in arrears, including expiration of yearly/monthly resources and fee deduction failure of pay-per-use resources. POLICE: The cloud service is frozen for public security. ILLEGAL: The cloud service is frozen due to violation of laws and regulations. VERIFY: The cloud service is frozen because the user fails to pass the real-name authentication. PARTNER: A partner freezes their customer's resources.

**Table 10** ResourceTag
Parameter	Type	Description
key	String	Specifies the tag key. The key must meet the following requirements: The key can contain 1 to 128 characters. The key can contain UTF-8 letters, digits, spaces, and the following characters:_.:=+-@ Tags starting with _sys_ are system tags and cannot be entered by tenants.
value	String	Specifies the tag value. The value must meet the following requirements: The value can contain 0 to 255 characters. The key can contain UTF-8 letters, digits, spaces, and the following characters:_.:/=+-@ The value can be empty or null.

Example Requests

Changing the start port to 5000 and end port to 5200, retaining source IP address for client affinity, and modifying the name and description of the listener

PUT https://{ga_endpoint}/v1/listeners/1b11747a-b139-492f-9692-2df0b1c87193

{
  "listener" : {
    "name" : "listenerNameNew",
    "description" : "listener description new",
    "port_ranges" : [ {
      "from_port" : 5000,
      "to_port" : 5200
    } ],
    "client_affinity" : "SOURCE_IP"
  }
}

Example Responses

Status code: 200

Operation succeeded.

{
  "listener" : {
    "id" : "1b11747a-b139-492f-9692-2df0b1c87193",
    "name" : "listenerNameNew",
    "description" : "listener description new",
    "protocol" : "TCP",
    "status" : "ACTIVE",
    "port_ranges" : [ {
      "from_port" : 5000,
      "to_port" : 5200
    } ],
    "client_affinity" : "SOURCE_IP",
    "accelerator_id" : "ac1bf54f-6a23-4074-af77-800648d25bc8",
    "created_at" : "2019-01-08T01:21:37.151Z",
    "updated_at" : "2019-01-08T01:21:37.151Z",
    "domain_id" : "99a3fff0d03c428eac3678da6a7d0f24",
    "frozen_info" : {
      "status" : 2,
      "effect" : 1,
      "scene" : [ "ARREAR", "POLICE" ]
    },
    "tags" : [ {
      "key" : "tagKey",
      "value" : "tagValue"
    } ]
  },
  "request_id" : "915a14a6-867b-4af7-83d1-70efceb146f9"
}