You need to enable JavaScript to run this app.
导航
应用型负载均衡
  • 文档首页
    • /应用型负载均衡/开发指南/API 参考/监听接口/CreateListener
CreateListener
最近更新时间：2024.10.11 18:10:07首次发布时间：2022.05.20 21:30:37
我的收藏

请求说明

API 名称：CreateListener。
API 域名：open.volcengineapi.com 。
API 描述：创建监听器。

使用限制

节流限制：每秒最多提交 5 个 API 请求。

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

URI 参数

在使用该部分 API 提交请求时必须包含以下 URI 参数。

除了 URI 参数，该 API 请求还需要包含签名参数。关于更多签名参数的信息，参见公共请求参数。

名称类型是否必选格式说明
Action
string
是
[a-zA-Z]+
API 名称，如 CreateListener。
Versionstring是YYYY-MM-DDAPI 版本信息。该参数的取值是 2020-04-01 。
X-Expiresint否900表示签名的有效时间，单位是秒，默认值是900。

请求参数

在使用该 API 提交请求时，请求参数中可以包含的参数如下。

参数类型是否必选参数说明示例值
LoadBalancerIdString是监听器所属的负载均衡实例ID
alb-abcderf******

ListenerName

String

否

监听器的名字。

  • 不填写时以“协议-端口”格式命名。
  • 不能以http://或https://开头。
  • 必须以字母或中文开头，可包含数字、点（.）、下划线（_）和短横线（-）。
  • 长度限制在1-128字符之间。

test

ProtocolString是监听器的协议，包括 HTTP 协议和 HTTPS 协议。HTTP
PortInteger是监听器的监听端口，取值：1 - 65535 。80

Enabled

String

否

监听器开启/关闭，取值如下：

  • on：开启（默认）。
  • off：关闭。

on

CertificateSource

String

否

监听器关联的默认证书的来源，该参数仅对 HTTPS 监听器有效，取值：

  • alb：表示通过 ALB 上传的证书。

  • cert_center：表示通过火山证书中心上传的证书。

cert_center

CertificateIdString否监听器关联的证书ID，创建 HTTPS 监听器且证书来源为 alb 时必传。cert-********
CertCenterCertificateIdString否监听器关联的证书ID，创建 HTTPS 监听器且证书来源为 cert_center 时必传。cert-********
CACertificateIdString否监听器关联的 CA 证书 ID，创建 HTTPS 监听器时指定 CA 证书，则支持双向认证，否则为单向认证。cert-********
ServerGroupIdString是监听器关联的默认服务器组 ID 。rsp-********

EnableHttp2

String

否

HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效，取值如下：

  • on：开启。
  • off：关闭（默认）。

off

EnableQuic

String

否

QUIC 特性开关，该参数仅对 HTTPS 监听器有效，取值如下：

  • on：开启。
  • off：关闭（默认）。

off

AclStatus

String

否

是否开启访问控制功能。取值如下：

  • on：开启。
  • off ：不开启（默认）。

off

AclType

String

否

访问控制的方式。取值如下:

  • white：白名单方式。表示监听器仅转发来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器不会转发任何请求。
  • black：黑名单方式。表示仅拒绝来自所选访问控制策略组中设置的IP地址或地址段的请求。如果所选策略组中没有添加任何IP，则监听器会转发全部请求。
    当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。

black

AclIds.N

List of String

否

监听器绑定的访问控制策略组ID。

  • - N：表示访问控制策略组的序号，数量上限为5个。
  • 多个访问控制策略组ID间使用“&”分隔。
    当AclStatus参数配置为 on 时，AclType和AclIds.N为必填。

AclIds.1=acl-3cj44nv0jhhxc6c6rrtet****& AclIds.2=acl-2febxt4pu0zy85oxruw0t****

Description

String

否

监听器的描述信息。

  • 不能以http://或https://开头。
  • 必须以字母或中文开头，可包含数字、英文逗号（,）、点号（.）、下划线（_）、空格（ ）、等号（=）、短横线（-）、中文逗号（，）、中文句号（。） 。
  • 长度限制为1 ～ 255个字符。
  • 不填默认为空字符串。

test

DomainExtensions

-

否

需要关联的扩展域名列表，仅HTTPS监听器生效。
具体请参见下表 DomainExtensions 。

-

TagsArray否监听器所属标签，具体参见下表 Tags。-

DomainExtensions

参数类型是否必选参数说明示例值

DomainExtensions.N.Domain

List of Struct

否

域名。 - N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。 具体格式规范如下：

  • 通常不能为空。但是如果实例支持自动选择扩展证书，即SniAutoMatch为on，则DomainExtensions.N.Domain需传入空字符串。
  • 需至少包含一个‘.’，且不允许以‘.’开头或结尾。
  • 仅允许包含小写字母、数字、‘.’、‘-‘、‘*’。
  • 长度限制为1 ～ 128个字符。
  • 泛域名：使用“*”代替1个或多个字符。
    • “*”必须在域名开头或结尾。
    • 同一条域名中“*”不能出现两次。
    • “*”前后不能有除了.以外的字符。
    • 合法示例：*.com、www.test.*。
    • 非法示例：*aaa.com、www.*.com 。
    • 精确域名：符合域名规范的精确域名，例如：www.test.com。
  • 同一HTTPS监听器下的域名不能重复。
  • 匹配域名时，对域名的大小写不敏感。
DomainExtensions.1.Domain=abc.com&DomainExtensions.2.Domain=def.com

DomainExtensions.N.CertificateSource

String

否

  • 域名使用的服务器证书来源，取值：

    • alb：表示通过 ALB 上传的证书

    • cert_center：表示通过火山证书中心上传的证书

  • - N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。
DomainExtensions.1.CertificateSource=cert_center&DomainExtensions.2.CertificateSource=alb

DomainExtensions.N.CertificateId

String

否

  • 域名使用的服务器证书。当证书来源为 alb 时有效。

  • - N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。

DomainExtensions.1.CertificateId=cert-qwertyuqwert&DomainExtensions.2.CertificateId=cert-zxcvbgasdfn

DomainExtensions.N.CertCenterCertificateId

String

否

  • 域名使用的服务器证书。 当证书来源为 cert_center 时有效。

  • - N：表示域名的序号，一个HTTPS监听器能关联的扩展域名上限为20个，取值1～20。

DomainExtensions.1.CertCenterCertificateId=cert-qwertyuqwert&DomainExtensions.2.CertCenterCertificateId=cert-zxcvbgasdfn

Tags

参数

类型

是否必选

参数说明

示例

Tags.N.Key

String

是

用户标签的标签键。具体规则如下：

  • 长度限制为1～128个字符。

  • 大小写敏感。

  • 不能以volc:的任意大小写组合开头。

  • 不能以空格开头或结尾。

  • 允许包含各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、减号（-）和@。

  • 同一资源的标签键不允许重复。

Tags.1.Key=k1&Tags.2.Key=k2

Tags.N.Value

String

否

用户标签的标签值。如果传入该参数，则必须先传入Tags.N.Key。具体规则如下：

  • 长度限制为0～256个字符。

  • 大小写敏感。

  • 不能以空格开头或结尾。

  • 允许包含各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、减号（-）和@。

Tags.1.Value=v1&Tags.2.Value=v2

返回参数

参数类型参数说明示例值
RequestId
String
请求 ID。
20210811152539010225146063030****
ListenerIdString监听器 ID。lsn-2fek3rgsxhrsw5oxruwec****

示例

请求示例

GET /?Action=CreateListener&CertificateId=&Description=test&Enabled=on&ListenerName=TEST&LoadBalancerId=alb-1g1f1c6a****88ibuxws5k0k3&Port=12&Protocol=HTTP&ServerGroupId=rsp-2ff2u2282****5oxruwe33hdz&Version=2020-04-01" HTTP/1.1
Host: open.volcengineapi.com
Region: cn-beijing
ServiceName: alb

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20210816110638****2514606306AF947C",
        "Action": "CreateListener",
        "Version": "2020-04-01",
        "Service": "alb",
        "Region": "cn-beijing"
    },
    "Result": {
        "RequestId": "202108161106****22514606306AF947C",
        "ListenerId": "lsn-1g0swqx5fnqbk8ibuxyfxp2rd"
    }
}

错误码

如果响应正文包含 Error 字段，则表示 API 请求失败。此处仅展示当前 API 的错误码，更多错误码请参见公共错误码。

HTTP Code

错误码

错误信息

错误描述

400

OperationDenied.AccountArrears

The request on the specified resource is denied due to the account being in arrears status.

因账号处于欠费状态，对于该资源的操作请求被拒绝。

400InvalidPort.MalformedThe specified Port is malformed.指定的 Port 参数格式不合法。

400

MissingParameter

The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'ServerGroupId'.

该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: ServerGroupId。

400

MissingParameter

The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CertificateId'.

该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CertificateId。

400

MissingParameter

The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CertCenterCertificateId'.

该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CertCenterCertificateId。

400MissingParameterThe request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'DomainExtensions.CertificateId'.该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: DomainExtensions.CertificateId。
400MissingParameterThe request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'DomainExtensions.CertCenterCertificateId'.该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: DomainExtensions.CertCenterCertificateId。

400

InvalidServerGroup.InvalidStatus

The specified ServerGroup is not in the correct status for the request.

指定的服务器组所处状态无法响应该请求。

400InvalidVpcForServerGroup.LoadBalancerMismatchThe specified VPC of ServerGroup and LoadBalancer do not match.指定的服务器组和 ALB 实例的 VPC 不匹配。
400InvalidListenerName.MalformedThe specified ListenerName is malformed.指定的 ListenerName 参数格式不合法。
400InvalidDescription.MalformedThe specified Description is malformed.指定的 Description 参数格式不合法。
400InvalidAclStatus.MalformedThe specified AclStatus is malformed.指定的 AclStatus 参数格式不合法。
400InvalidAclType.MalformedThe specified AclType is malformed.指定的 AclType 参数格式不合法。
400InvalidDomainExtensions.CertificateSource.MalformedThe specified DomainExtensions.CertificateSource is malformed.指定的 DomainExtensions.CertificateSource 参数格式不合法。

400

MissingParameter

The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'AclIds'.

该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: AclIds。

400InvalidAclId.DuplicatedThe specified AclId is duplicated.指定的 AclId 重复。
400OperationFailed.QueryProjectThe request on the specified resource failed due to the query on project failed.因查询项目失败，对于该资源的操作请求失败。

400

MissingParameter

The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, 'CertificateId'.

该请求缺少必要参数。请确保发起请求已提供全部必要参数，比如: CertificateId。

400

InvalidCertificateType.FunctionMismatch

The specified Certificate's type and Function do not match.

指定的证书的类型与预期功能不匹配。

400

InvalidServerCertificate.InvalidStatus

The specified Server Certificate is not in the correct status for the request.

指定的服务器证书所处状态无法响应该请求。

400InvalidCertificateServiceSSLCertificate.InvalidStatusThe specified Certificate Service SSL Certificate is not in the correct status for the request. Please check if the certificate has been issued.指定的证书中心 SSL 证书所处状态无法响应该请求。请确认证书处于已签发状态。
400InvalidIndexOrder.MalformedThe specified index order is malformed.指定的索引顺序参数格式不合法。

400

InvalidDomainExtensions.Domain.Malformed

The specified DomainExtensions.Domain is malformed.

指定的 DomainExtensions.Domain 参数格式不合法。

400

InvalidDomainExtensions.Domain.Duplicated

The specified DomainExtensions.Domain is duplicated. Domain Extensions in one listener can not be same.

指定的 DomainExtensions.Domain 重复。一个监听器下关联的扩展域名不能重复。

400InvalidDomainExtensions.Certificate.InvalidStatusThe specified DomainExtension Certificate is not in the correct status for the request.指定的扩展域名证书所处状态无法响应该请求。

400

InvalidCACertificate.InvalidStatus

The specified CA Certificate is not in the correct status for the request.

指定的 CA 证书所处状态无法响应该请求。

400InvalidProtocol.MalformedThe specified Protocol is malformed.指定的 Protocol 参数格式不合法。
400InvalidEnabled.MalformedThe specified Enabled is malformed.指定的 Enabled 参数格式不合法。
400InvalidEnableHttp2.MalformedThe specified EnableHttp2 is malformed.指定的 EnableHttp2 参数格式不合法。
400InvalidEnableQuic.MalformedThe specified EnableQuic is malformed.指定的 EnableQuic 参数格式不合法。

400

InvalidCertificateSource.Malformed

The specified CertificateSource is malformed.

指定的 CertificateSource 参数格式不合法。

400

OperationDenied.DualStackEnableQuicUnsupported

The request on the specified Listener is denied due to the dual stack load balancer listener not support to enable quic.

因双栈 ALB 实例暂时不支持监听器开启 Quic，对于该监听器的操作请求被拒绝。

400OperationFailed.QueryIAMThe request on the specified resource failed due to the query on IAM failed.因请求 IAM 失败，对于该资源的操作请求失败。
400OperationFailed.QueryCertificateServiceThe request on the specified resource failed due to the query on Certificate Service failed.因请求证书中心服务失败，对于该资源的操作请求失败。

400

OperationFailed.OperateGtmFailed

The request on the specified resource failed due to operating gtm failed.

因操作 GTM 实例失败，对于该资源的操作请求失败。

400

OperationFailed.AddIntoProjectFailed

The request on the specified resource failed due to adding it into the project failed.

因将资源加入至项目中失败，对于该资源的操作请求失败。

400QuotaExceed.ListenerPerInstanceYou've reached the limit on the number of listeners per ALB you can add in, resource xxx, usage xx/xx.已达到每个 ALB 实例可创建的监听器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。
400QuotaExceed.ServerPerInstanceYou've reached the limit on the number of backend servers per ALB you can associate with, resource xxx, usage xx/xx.已达到每个实例可关联的后端服务器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。

400

QuotaExceed.SniDomainPerListener

You've reached the limit on the number of sni domains per listener you can associate with, resource xxx, usage xx/xx.

已达到每个监听器可关联的 sni 域名的数量上限。资源是xxx，目前已使用xxx，配额为xxx。

400

QuotaExceed.AclPerListener

You've reached the limit on the number of ACLs per listener you can associate with, resource xxx, usage xx/xx.

已达到每个监听器可关联的 ACL 的数量上限。资源是xxx，目前已使用xxx，配额为xxx。

400QuotaExceed.ListenerPerAclYou've reached the limit on the number of listeners per ACL you can associate with, resource xxx, usage xx/xx.已达到每个 ACL 可关联的监听器的数量上限。资源是xxx，目前已使用xxx，配额为xxx。
400QuotaExceed.RulePerGroupYou've reached the limit on the number of rules per server group you can associate with, resource xxx, usage xx/xx.已达到每个服务器组可关联转发规则的数量上限。资源是xxx，目前已使用xxx，配额为xxx。

400

OperationFailed.AddTagFailed

The request on the specified resource failed due to adding tag to the resource failed.

因给资源添加标签失败失败，对于该资源的操作请求失败。

400

InvalidCertificateId.Duplicated

The specified CertificateId is duplicated. Certificates in one listener can not be same.

指定的 CertificateId 重复。一个监听器下的证书不能重复。

404

InvalidLoadBalancer.NotFound

The specified LoadBalancer does not exist.

指定的 ALB 实例不存在。

404

InvalidServerGroup.NotFound

The specified ServerGroup does not exist.

指定的服务器组不存在。

404

InvalidAcl.NotFound

The specified ACL does not exist.

指定的 ACL 不存在。

404InvalidProject.NotFoundThe specified Project does not exist.指定的项目不存在。
404InvalidServerCertificate.NotFoundThe specified Server Certificate does not exist.指定的服务器证书不存在。

404

InvalidDomainExtensions.Certificate.NotFound

The specified DomainExtension Certificate does not exist.

指定的扩展域名证书不存在。

404InvalidCACertificate.NotFoundThe specified CA Certificate does not exist.指定的 CA 证书不存在。

409

InvalidPort.Conflict

The specified Port already exists.

指定的端口已存在。