調用CreateListener介面建立監聽-負載平衡-阿里雲 - Server Load Balancer

建立監聽。

介面說明

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	是	應用型Server Load Balancer執行個體 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	是	Server Load Balancer執行個體前端使用的連接埠。取值：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`頭欄位擷取對訪問Server Load Balancer執行個體用戶端認證的校正結果。取值： true：是。 false（預設值）：否。說明僅 HTTPS 監聽支援此參數。	true
XForwardedForClientCertFingerprintAlias	string	否	自訂頭名稱，只有當 XForwardedForClientCertFingerprintEnabled 的值為 true 時生效。取值：1~40 個字元。支援字母 a~z、短劃線（-）、底線（_）和數字。說明僅 HTTPS 監聽支援此參數。	test_finger-print-alias_123456
XForwardedForClientCertFingerprintEnabled	boolean	否	是否通過`X-Forwarded-Clientcert-fingerprint`頭欄位擷取訪問Server Load Balancer執行個體用戶端認證的指紋取值。取值： true：是。 false（預設值）：否。說明僅 HTTPS 監聽支援此參數。	true
XForwardedForClientCertIssuerDNAlias	string	否	自訂頭名稱，只有當 XForwardedForClientCertIssuerDNEnabled 的值為 true 的時候，此值才會生效。取值：1~40 個字元。支援字母 a~z、短劃線（-）、底線（_）和數字。說明僅 HTTPS 監聽支援此參數。	test_issue-dn-alias_123456
XForwardedForClientCertIssuerDNEnabled	boolean	否	是否通過`X-Forwarded-Clientcert-issuerdn`頭欄位擷取訪問Server Load Balancer執行個體用戶端認證的發行者資訊。取值： true：是。 false（預設值）：否。說明僅 HTTPS 監聽支援此參數。	true
XForwardedForClientCertSubjectDNAlias	string	否	自訂頭名稱，只有當 XForwardedForClientCertSubjectDNEnabled 的值為 true 時，此值才會生效。取值：1~40 個字元。支援字母 a~z、短劃線（-）、底線（_）和數字。說明僅 HTTPS 監聽支援此參數。	test_subject-dn-alias_123456
XForwardedForClientCertSubjectDNEnabled	boolean	否	是否通過`X-Forwarded-Clientcert-subjectdn`頭欄位擷取訪問Server Load Balancer執行個體用戶端認證的所有者資訊。取值： true：是。 false（預設值）：否。說明僅 HTTPS 監聽支援此參數。	true
XForwardedForClientSrcPortEnabled	boolean	否	是否通過`X-Forwarded-Client-srcport`頭欄位擷取訪問Server Load Balancer執行個體用戶端的連接埠。取值： true：是。 false（預設值）：否。說明 HTTP 和 HTTPS 監聽支援此參數。	true
XForwardedForEnabled	boolean	否	是否通過`X-Forwarded-For`頭欄位擷取來訪者真實 IP。取值： true（預設值）：是。 false：否。說明配置 true，XForwardedForProcessingMode 預設取值 append，支援修改為 remove。配置 false，ALB 將請求發送至後端服務之前保留`X-Forwarded-For`頭欄位，不做額外處理。 HTTP 和 HTTPS 監聽支援此參數。	true
XForwardedForProcessingMode	string	否	處理`X-Forwarded-For`頭欄位的模式。只有當 XForwardedForEnabled 為 true 時，此值才會生效。取值： append（預設值）：附加。 remove：刪除。說明配置 append，將請求發送至後端服務之前把最後一跳 IP 加入`X-Forwarded-For`頭欄位。配置 remove，請求發送至後端服務之前刪除`X-Forwarded-For`標題，無論請求是否攜帶`X-Forwarded-For`頭欄位。 HTTP 和 HTTPS 監聽支援此參數。	append
XForwardedForProtoEnabled	boolean	否	是否通過`X-Forwarded-Proto`頭欄位擷取Server Load Balancer執行個體的監聽協議。取值： true：是。 false（預設值）：否。說明 HTTP、HTTPS 和 QUIC 監聽支援此參數。	false
XForwardedForSLBIdEnabled	boolean	否	是否通過`SLB-ID`頭欄位擷取Server Load Balancer執行個體 ID。取值： true：是。 false（預設值）：否。說明 HTTP、HTTPS 和 QUIC 監聽支援此參數。	false
XForwardedForSLBPortEnabled	boolean	否	是否通過`X-Forwarded-Port`頭欄位擷取Server Load Balancer執行個體的監聽連接埠。取值： 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`頭欄位擷取訪問Server Load Balancer執行個體用戶端的網域名稱。取值： 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 個預設伺服器憑證。說明當 ListenerProtocol 參數取值為 HTTPS 或 QUIC 的時候，此參數為必填。如需更多伺服器憑證，可在建立監聽後調用 AssociateAdditionalCertificatesWithListener 配置擴充認證。	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不存在。

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。