CreateListener

1. API Description

This API is used to create a load balance listener.

2. Input Parameters

The following request parameter list only provides API request parameters.

Parameter Name	Required	Type	Description
loadBalancerId	Yes	String	Load balance instance ID.
listenerName	Yes	String	Name of the listener to be created. Only letters, numbers, hyphens (-), and periods (.) are supported, and the beginning and end must be letters or numbers.
healthCheck	No	HealthCheck	Parameters related to health check. If this parameter is not passed or healthCheck.enable = false, the health check will be disabled.
protocol	Yes	ListenerProtocol	Listening protocols.
scheduler	Yes	ListenerScheduler	Listening forwarding rules.
port	Yes	String	Listening port. Multiple ports are separated by commas. When the port is a range, connect with -, for example: 10000-10005. The value range of the port is 1 to 65535. Please note that the port cannot overlap with other ports of the listener.
kind	No	LoadBalancerKind	Forwarding mode. If this parameter is not specified, a default value will be applied according to the region where the load balancer instance resides. Default value: DNAT or FNAT.

3. Output Parameters

Parameter Name	Type	Description
requestId	String	The unique request ID, which is returned for each request. RequestId is required to locate a problem.
listenerId	String	The created listener ID.

4. Code Example

Example

1. Create a TCP load balance listener to listen to ports 8080-9000 and 8000 without enabling health check.

POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateListener
<Common Request Params>

Request：
{
  "loadBalancerId" : "<loadBalancerId>",
  "listenerName" : "sample",
  "protocol" : "TCP",
  "scheduler" : "mh",
  "port" : "8080-9000,8000"
}

Response：
{
  "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
  "response": {
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "listenerId": "<listenerId>"
  }
}

1. Create a TCP load balance listener and enable health check at the same time.

POST /api/v2/zlb HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: CreateListener
<Common Request Params>

Request：
{
  "loadBalancerId" : "<loadBalancerId>",
  "listenerName" : "sample",
  "protocol" : "TCP",
  "scheduler" : "mh",
  "healthChekc": {
      "enabled": true,
      "checkType": "HTTP_GET",
      "checkPort": null,
      "checkDelayLoop": 3,
      "checkConnTimeout": 2,
      "checkRetry": 2,
      "checkDelayTry": 2,
      "checkHttpGetUrl": "/health",
      "checkHttpStatusCode": 200
  }
  "port" : "8080"
}

Response：
{
  "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
  "response": {
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
    "listenerId": "<listenerId>"
  }
}

5. Developer Resources

Zenlayer Cloud API 2.0 SDKs to make it easier for you to call APIs. More programming languages will be supported.

6. Error Codes

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

HTTP Status Code	Error Code	Description
409	INVALID_BACKEND_INSTANCE_LISTENER_EXIST	The backend server already exists.
409	INVALID_BACKEND_INSTANCE_MULTIPLE	Duplicate backend server.
400	INVALID_BACKEND_IP_ADDRESS	No instance found for the backend server’s private IP address.
409	INVALID_BACKEND_IP_ZBG_REQUIRED	The backend server IP to be added requires a Border Gateway.
400	INVALID_BACKEND_SERVER_IP_INVALID	Invalid backend server IP. A private IP address is required.
409	INVALID_BACKEND_SERVER_IP_REPEAT	Duplicate backend server IP address.
400	INVALID_BACKEND_SERVER_PORT	The specified port is not allowed in DR mode or when listening on multiple ports.
400	INVALID_INSTANCE_IP_ADDRESS	Invalid instance private IP address.
404	INVALID_INSTANCE_NOT_FOUND	The instance does not exist.
404	INVALID_LB_LISTENER_NOT_FOUND	The listener does not exist.
404	INVALID_LB_NOT_FOUND	The load balancer does not exist.
400	INVALID_LB_STATUS	The current load balancer status does not allow this operation.
400	INVALID_LISTENER_KIND_NOT_SUPPORT	The specified listener type is not supported in this region.
409	INVALID_LISTENER_PORT_CONFLICT	The port conflicts with another listener.
409	INVALID_LISTENER_PORT_CONFLICT_SELF	The configured port is invalid due to a conflict.
400	INVALID_LISTENER_QUOTA_EXCEED	The number of listeners on the load balancer exceeds limit.