Updated on 2023-12-06 GMT+08:00

Adding a Listener

Function

This API is used to add a listener.

Calling Method

For details, see Calling APIs.

URI

POST /v1/listeners

Request Parameters

Table 1 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 2 Request body parameters

Parameter

Mandatory

Type

Description

listener

Yes

CreateListenerOption object

Specifies the detailed information about adding a listener.

Table 3 CreateListenerOption

Parameter

Mandatory

Type

Description

name

Yes

String

Specifies the listener name. The name can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.

Minimum: 1

Maximum: 64

description

No

String

Specifies the information about the listener. The value can contain 0 to 255 characters. The following characters are not allowed: <>

Minimum: 0

Maximum: 255

protocol

Yes

String

Specifies the protocol used by the listener to forward requests.

Enumeration values:

  • TCP

  • UDP

port_ranges

Yes

Array of PortRange objects

Specifies the port range used by the listener.

Array Length: 1 - 10

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.

Enumeration values:

  • SOURCE_IP

  • NONE

accelerator_id

Yes

String

Specifies the ID of the global accelerator associated with the listener.

Minimum: 0

Maximum: 36

tags

No

Array of ResourceTag objects

Specifies the tags.

Array Length: 1 - 20

Table 4 PortRange

Parameter

Mandatory

Type

Description

from_port

Yes

Integer

Specifies the start port number.

Minimum: 1

Maximum: 65535

to_port

Yes

Integer

Specifies the end port number.

Minimum: 1

Maximum: 65535

Table 5 ResourceTag

Parameter

Mandatory

Type

Description

key

Yes

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.

Minimum: 1

Maximum: 128

value

Yes

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.

Minimum: 0

Maximum: 255

Response Parameters

Status code: 201

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.

Minimum: 1

Maximum: 64

description

String

Specifies the information about the listener. The value can contain 0 to 255 characters. The following characters are not allowed: <>

Minimum: 0

Maximum: 255

protocol

String

Specifies the protocol used by the listener to forward requests.

Enumeration values:

  • TCP

  • UDP

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.

Enumeration values:

  • ACTIVE

  • PENDING

  • ERROR

  • DELETING

port_ranges

Array of PortRange objects

Specifies the port range used by the listener.

Array Length: 1 - 10

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.

Enumeration values:

  • SOURCE_IP

  • NONE

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.

Minimum: 1

Maximum: 65535

to_port

Integer

Specifies the end port number.

Minimum: 1

Maximum: 65535

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.)

Minimum: 0

Maximum: 2

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.

Minimum: 1

Maximum: 3

Default: 1

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.

Maximum: 16

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.

Minimum: 1

Maximum: 128

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.

Minimum: 0

Maximum: 255

Example Requests

Creating a listener whose protocol is TCP, start port is 4000, end port is 4200, and client affinity is source IP address

POST https://{ga_endpoint}/v1/listeners

{
  "listener" : {
    "name" : "listenerName",
    "description" : "listener description",
    "protocol" : "TCP",
    "port_ranges" : [ {
      "from_port" : 4000,
      "to_port" : 4200
    } ],
    "client_affinity" : "SOURCE_IP",
    "accelerator_id" : "ac1bf54f-6a23-4074-af77-800648d25bc8",
    "tags" : [ {
      "key" : "tagKey",
      "value" : "tagValue"
    } ]
  }
}

Example Responses

Status code: 201

Listener added.

{
  "listener" : {
    "id" : "1b11747a-b139-492f-9692-2df0b1c87193",
    "name" : "listenerName",
    "description" : "listener description",
    "protocol" : "TCP",
    "status" : "ACTIVE",
    "port_ranges" : [ {
      "from_port" : 4000,
      "to_port" : 4200
    } ],
    "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"
}

Status Codes

Status Code

Description

201

Listener added.

Error Codes

See Error Codes.