AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

CreateListener - 创建监听

更新时间：
复制为 MD 格式
产品详情
我的收藏

创建监听。

接口说明

CreateListener 接口属于异步接口，即系统返回一个请求 ID，但该 HTTP、HTTPS 或 QUIC 监听尚未创建成功，系统后台的创建任务仍在进行。您可以调用 GetListenerAttribute 查询 HTTP、HTTPS 或 QUIC 监听的创建状态：

  • 当 HTTP、HTTPS 或 QUIC 监听处于 Provisioning 状态时，表示 HTTP、HTTPS 或 QUIC 监听正在创建中。

  • 当 HTTP、HTTPS 或 QUIC 监听处于 Running 状态时，表示 HTTP、HTTPS 或 QUIC 监听创建成功。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

alb:CreateListener

create

*LoadBalancer

acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

*SecurityPolicy

acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}

*ServerGroup

acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}
  • alb:ListenerProtocol
 无

请求参数

名称

类型

必填

描述

示例值
LoadBalancerId

string

是

应用型负载均衡实例 ID。

alb-n5qw04uq8vavfe****
ClientToken

string

否

客户端 Token，用于保证请求的幂等性。

从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符。

说明

若您未指定，则系统自动使用 API 请求的 RequestId 作为 ClientToken 标识。每次 API 请求的 RequestId 不一样。

123e4567-e89b-12d3-a456-426655440000
DryRun

boolean

否

是否只预检此次请求，取值：

  • true：发送检查请求，不会创建监听。检查项包括是否填写了必需参数、请求格式、业务限制。如果检查不通过，则返回对应错误。如果检查通过，则返回错误码DryRunOperation。

  • false（默认值）：发送正常请求，通过检查后返回 HTTP 2xx 状态码并直接进行操作。

false
ListenerProtocol

string

是

监听协议。

取值：HTTP、HTTPS 或 QUIC。

HTTP
ListenerPort

integer

是

负载均衡实例前端使用的端口。

取值：1~65535。

80
ListenerDescription

string

否

自定义监听名称。

长度为 2~256 个字符，必须是中文和无害字符串中的字符，可包含中文、字母、数字、短划线（-）、正斜线（/）、半角句号（.）、下划线（_）。

HTTP_80
RequestTimeout

integer

否

指定请求超时时间。单位：秒。

取值：1~600。

默认值：60。

如果在超时时间内后端服务器一直没有响应，负载均衡将放弃等待，并给客户端返回HTTP 504错误码。

说明

用户可以申请提升配额将请求超时时间提升至最大 3600 秒。

60
IdleTimeout

integer

否

指定连接空闲超时时间。单位：秒。

取值范围：1~600。

默认值：15。

如果在超时时间内一直没有访问请求，负载均衡会暂时中断当前连接，直到一下次请求来临时重新建立新的连接。

说明

用户可以申请提升配额将连接空闲超时时间提升至最大 3600 秒。

3
GzipEnabled

boolean

否

是否开启Gzip压缩，对特定文件类型进行压缩。取值：

  • true（默认值）：是。

  • false：否。

true
Http2Enabled

boolean

否

是否开启HTTP/2特性。取值：

  • true（默认值）：是。

  • false：否。

说明

仅 HTTPS 监听支持此参数。

true
SecurityPolicyId

string

否

安全策略 ID。支持系统安全策略和自定义安全策略。

默认值：tls_cipher_policy_1_0（系统安全策略）。

说明

仅 HTTPS 监听支持此参数。

tls_cipher_policy_1_0
CaEnabled

boolean

否

是否开启双向认证。取值：

  • true：开启。

  • false（默认值）：不开启。

false
XForwardedForConfig

object

否

XForward 字段配置信息。

XForwardedForClientCertClientVerifyAlias

string

否

自定义头名称，只有当 XForwardedForClientCertClientVerifyEnabled 的值为 true 的时候，该值才会生效；否则该值不会生效。

取值：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。

说明

仅 HTTPS 监听支持此参数。

test_client-verify-alias_123456
XForwardedForClientCertClientVerifyEnabled

boolean

否

是否通过X-Forwarded-Clientcert-clientverify头字段获取对访问负载均衡实例客户端证书的校验结果。取值：

  • true：是。

  • false（默认值）：否。

说明

仅 HTTPS 监听支持此参数。

true
XForwardedForClientCertFingerprintAlias

string

否

自定义头名称，只有当 XForwardedForClientCertFingerprintEnabled 的值为 true 时生效。

取值：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。

说明

仅 HTTPS 监听支持此参数。

test_finger-print-alias_123456
XForwardedForClientCertFingerprintEnabled

boolean

否

是否通过X-Forwarded-Clientcert-fingerprint头字段获取访问负载均衡实例客户端证书的指纹取值。取值：

  • true：是。

  • false（默认值）：否。

说明

仅 HTTPS 监听支持此参数。

true
XForwardedForClientCertIssuerDNAlias

string

否

自定义头名称，只有当 XForwardedForClientCertIssuerDNEnabled 的值为 true 的时候，此值才会生效。

取值：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。

说明

仅 HTTPS 监听支持此参数。

test_issue-dn-alias_123456
XForwardedForClientCertIssuerDNEnabled

boolean

否

是否通过X-Forwarded-Clientcert-issuerdn头字段获取访问负载均衡实例客户端证书的发行者信息。取值：

  • true：是。

  • false（默认值）：否。

说明

仅 HTTPS 监听支持此参数。

true
XForwardedForClientCertSubjectDNAlias

string

否

自定义头名称，只有当 XForwardedForClientCertSubjectDNEnabled 的值为 true 时，此值才会生效。

取值：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。

说明

仅 HTTPS 监听支持此参数。

test_subject-dn-alias_123456
XForwardedForClientCertSubjectDNEnabled

boolean

否

是否通过X-Forwarded-Clientcert-subjectdn头字段获取访问负载均衡实例客户端证书的所有者信息。取值：

  • true：是。

  • false（默认值）：否。

说明

仅 HTTPS 监听支持此参数。

true
XForwardedForClientSrcPortEnabled

boolean

否

是否通过X-Forwarded-Client-srcport头字段获取访问负载均衡实例客户端的端口。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP 和 HTTPS 监听支持此参数。

true
XForwardedForEnabled

boolean

否

是否通过X-Forwarded-For头字段获取来访者真实 IP。取值：

  • true（默认值）：是。

  • false：否。

说明

  1. 配置 true，XForwardedForProcessingMode 默认取值 append，支持修改为 remove。

  2. 配置 false，ALB 将请求发送至后端服务之前保留X-Forwarded-For头字段，不做额外处理。

  3. HTTP 和 HTTPS 监听支持此参数。

true
XForwardedForProcessingMode

string

否

处理X-Forwarded-For头字段的模式。只有当 XForwardedForEnabled 为 true 时，此值才会生效。取值：

  • append（默认值）：附加。

  • remove：删除。

说明

  1. 配置 append，将请求发送至后端服务之前把最后一跳 IP 加入X-Forwarded-For头字段。

  2. 配置 remove，请求发送至后端服务之前删除X-Forwarded-For标头，无论请求是否携带X-Forwarded-For头字段。

  3. HTTP 和 HTTPS 监听支持此参数。

append
XForwardedForProtoEnabled

boolean

否

是否通过X-Forwarded-Proto头字段获取负载均衡实例的监听协议。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP、HTTPS 和 QUIC 监听支持此参数。

false
XForwardedForSLBIdEnabled

boolean

否

是否通过SLB-ID头字段获取负载均衡实例 ID。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP、HTTPS 和 QUIC 监听支持此参数。

false
XForwardedForSLBPortEnabled

boolean

否

是否通过X-Forwarded-Port头字段获取负载均衡实例的监听端口。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP、HTTPS 和 QUIC 监听支持此参数。

false
XForwardedForClientSourceIpsEnabled

boolean

否

是否允许 ALB 从 X-Forwarded-For 头字段中查找真实客户端 IP。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP、HTTPS 监听支持此参数。

false
XForwardedForClientSourceIpsTrusted

string

否

指定可信的代理 IP。

应用型负载均衡 ALB 会从后往前遍历X-Forwarded-For，选取第一个不在可信 IP 列表中的 IP 作为真实的客户端 IP，该 IP 会被用于源 IP 限速。

10.1.1.0/24
XForwardedForHostEnabled

boolean

否

是否开启通过X-Forwarded-Host头字段获取访问负载均衡实例客户端的域名。取值：

  • true：是。

  • false（默认值）：否。

说明

HTTP、HTTPS 和 QUIC 监听支持此参数。

false
QuicConfig

object

否

配置关联的 QUIC 监听。

QuicListenerId

string

否

需要关联的 QUIC 监听 ID，HTTPS 监听时有效，当 QuicUpgradeEnabled 为 true 时该参数必选。

说明

原始监听和关联的 QUIC 监听必须属于同一个 ALB 实例，并且此 QUIC 监听之前没有被关联过。

lsn-o4u54y73wq7b******
QuicUpgradeEnabled

boolean

否

是否开启 QUIC 升级。取值：

  • true：是。

  • false（默认值）：否。

说明

仅 HTTPS 监听支持此参数。

false
Certificates

array<object>

否

证书列表信息。

object

否

证书结构体。

CertificateId

string

否

默认证书 ID，目前仅支持添加 1 个默认服务器证书。

说明

103705*******
CaCertificates

array<object>

否

监听配置的 CA 证书列表。目前仅支持添加 1 个 CA 证书。

object

否

监听配置的 CA 证书结构。

CertificateId

string

否

CA 证书 ID。

说明

当 CaEnabled 参数取值为 true 的时候，此参数为必填。

123157*******
DefaultActions

array<object>

是

规则动作列表。

array<object>

是

规则动作列表。

ForwardGroupConfig

object

是

转发动作对应的配置。最多支持添加 20 个转发动作对应的配置。

ServerGroupTuples

array<object>

是

转发目标服务器元组。

object

是

转发目标服务器元组。

ServerGroupId

string

是

转发到的目的服务器组 ID。

sgp-8ilqs4axp6******
Type

string

是

动作类型。最多支持添加 1 个动作类型。

取值：ForwardGroup，表示转发至多个服务器组。

ForwardGroup
Tag

array<object>

否

标签。

object

否

标签结构。

Key

string

否

标签键。最多支持 128 个字符，不能以 aliyun 或 acs:开头，不能包含 http://或 https://。

env
Value

string

否

标签值。最多支持 128 个字符，不能以 aliyun 或 acs:开头，不能包含 http://或 https://。

product

返回参数

名称

类型

描述

示例值

object

创建监听。

JobId

string

异步任务 ID。

72dcd26b-f12d-4c27-b3af-18f6aed5****
ListenerId

string

监听 ID。

lsn-o4u54y73wq7b******
RequestId

string

请求 ID。

CEF72CEB-54B6-4AE8-B225-F876*******

示例

正常返回示例

JSON格式

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "ListenerId": "lsn-o4u54y73wq7b******",
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876*******"
}

错误码

HTTP status code

错误码

错误信息

描述
400 ResourceAlreadyExist.Listener The specified resource %s is already exist. 同端口监听已存在。
400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect. 实例的当前状态不支持本次操作。
400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s]  is incorrect. 资源%s [%s]的业务状态无效。
400 ResourceQuotaExceeded.LoadBalancerListenersNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制，资源是%s，目前已使用%s，配额为%s。
400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. 操作被拒绝，原因是%s。
400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. 资源%s已被关联。
400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 配额%s已超额度限制，资源是%s，目前已使用%s，配额为%s。
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 服务器组可被关联数已超额度限制。
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. 后端服务器数已超额度限制。
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. 服务器添加到组已超额度限制。
400 Mismatch.VpcId The %s is mismatched for %s and %s. %s在%s和%s中不匹配。
400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. 操作被拒绝，原因是ServerGroupProtocolNotSupport。
400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s. 操作被拒绝，原因是存在绑定本GRPC服务器组的监听没有启用HTTP2.0。
400 Mismatch.LoadBalancerEditionAndConnectionDrain The %s and %s are mismatched. 参数%s和%s不匹配。
400 Mismatch.LoadBalancerEditionAndSlowStartEnable The %s and %s are mismatched. 参数%s和%s不匹配。
400 InvalidParameter Invalid parameter, please check the parameter input. 无效参数，请检查参数输入。
400 OperationDenied.CACertificateCorrupted The CA certificate is corrupted. CA证书已经损坏
403 Forbidden.SecurityPolicy Authentication has failed for SecurityPolicy. 对SecurityPolicy鉴权失败
403 Forbidden.LoadBalancer Authentication is failed for %s. 负载均衡操作鉴权失败。
403 Forbidden.Listener Authentication is failed for %s. 监听鉴权失败。
404 ResourceNotFound.LoadBalancer The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.ServerGroup The specified resource %s is not found. 后端服务器组不存在。
404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. 资源%s不存在。
404 ResourceNotFound.Listener The specified resource %s is not found. 监听不存在。
404 ResourceNotFound.Certificate The specified resource %s is not found. 资源%s不存在。

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。

上一篇：监听下一篇：GetListenerAttribute - 查询监听器的属性