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

Querying Listeners

Function

This API is used to query listeners.

Calling Method

For details, see Calling APIs.

URI

GET /v1/listeners

Table 1 Query Parameters

Parameter

Mandatory

Type

Description

limit

No

Integer

Specifies the number of resources on each page. If this parameter is not specified, the default value is 500.

Minimum: 1

Maximum: 2000

Default: 500

marker

No

String

Specifies the ID of the resource from which pagination query starts, that is, the ID of the last resource on the previous page. If the parameter is not specified, only resources on the first page are queried. This parameter must be used together with limit.

Minimum: 1

Maximum: 36

page_reverse

No

Boolean

Specifies the page direction. The value can be true or false, and the default value is false. The last page in the list requested with page_reverse set to false will not contain the "next" link, and the last page in the list requested with page_reverse set to true will not contain the "previous" link.

Default: false

id

No

String

Specifies the resource ID.

Minimum: 0

Maximum: 36

name

No

String

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

Minimum: 0

Maximum: 64

status

No

String

Specifies the resource 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.

Minimum: 1

Maximum: 10

Enumeration values:

  • ACTIVE

  • PENDING

  • ERROR

  • DELETING

accelerator_id

No

String

Specifies the global accelerator ID.

Minimum: 0

Maximum: 36

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.

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

listeners

Array of ListenerDetail objects

Specifies the listeners.

page_info

PageInfo object

Specifies the pagination query information.

request_id

String

Specifies the request ID.

Table 4 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 5 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 6 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 7 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

Table 8 PageInfo

Parameter

Type

Description

next_marker

String

Specifies the marker of the next page. If this parameter is left empty, the resource is on the last page.

current_count

Integer

Specifies the number of resources on the current list.

Example Requests

Querying listeners

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

Example Responses

Status code: 200

Operation succeeded.

{
  "listeners" : [ {
    "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"
    } ]
  } ],
  "page_info" : {
    "next_marker" : "1b11747a-b139-492f-9692-2df0b1c87193",
    "current_count" : 1
  },
  "request_id" : "915a14a6-867b-4af7-83d1-70efceb146f9"
}

Status Codes

Status Code

Description

200

Operation succeeded.

Error Codes

See Error Codes.