CreateListener

1. API Description

This API (CreateListener) 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.
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.
healthCheck	No	HealthCheck	Parameters related to health check. If this parameter is not passed or healthCheck.enable = false, the health check will be disabled.
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.
persistent	No	Integer	Session persistence duration, in seconds. Value range: [0, 3600]

3. Output Parameters

Parameter Name	Type	Description
requestId	String	The unique request ID, which is returned for each request. RequestId is required for locating 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 integrates 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	Backend server already exists.
409	INVALID_BACKEND_INSTANCE_MULTIPLE	Duplicated backend servers.
400	INVALID_BACKEND_IP_ADDRESS	No instance found for the specified private IP of the backend server.
409	INVALID_BACKEND_IP_ZBG_REQUIRED	A border gateway is required for the VPC to which the backend server IP belongs.
400	INVALID_BACKEND_SERVER_IP_INVALID	Invalid backend server IP. The backend server IP must be a private IP.
409	INVALID_BACKEND_SERVER_IP_REPEAT	Duplicated backend server IPs.
400	INVALID_BACKEND_SERVER_PORT	When the forwarding mode is Direct Routing or a listener listens on multiple ports, the backend port must match and cannot be set manually.
400	INVALID_INSTANCE_IP_ADDRESS	The instance's private IP is invalid.
404	INVALID_INSTANCE_NOT_FOUND	Backend server does not exist.
404	INVALID_LB_LISTENER_NOT_FOUND	The listener does not exist.
404	INVALID_LB_NOT_FOUND	Load balancer does not exist.
400	INVALID_LB_STATUS	Load balancer state is not supported.
400	INVALID_LISTENER_KIND_NOT_SUPPORT	The specified listener type is not supported in this region.
400	INVALID_LISTENER_PERSISTENT_QUOTA_EXCEED	The session persistence duration of the load balancer listener exceeds the quota.
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.
400	INVALID_PORT_FORMAT_ERROR	Invalid port format.
400	INVALID_PORT_RANGE	Invalid port range. The port range should be between 1 and 65535.