使用CreateForwardingRules為監聽建立轉寄規則-Global Acceleration-阿里雲 - Global Accelerator

如果您的業務需要根據請求的屬性（網域、路徑等）或請求中包含的資料資訊（HTTP標頭、Cookie等）來進行流量分發和處理，您可以自訂監聽的轉發規則。監聽會根據轉發規則對存取請求執行不同的轉發動作。您可以透過呼叫CreateForwardingRules介面建立轉發規則。

介面說明

在您呼叫本介面建立轉發規則前，建議您先了解轉發規則原理及比對規則。更多資訊，請參見轉發策略。

呼叫本介面時，請注意以下事項：

CreateForwardingRules 介面屬於非同步介面，即系統會先回傳一個轉發策略 ID，但轉發策略並未建立完成，系統後台的建立任務仍在進行。您可以呼叫 ListForwardingRules 查詢轉發策略的狀態：
- 當轉發策略處於 configuring 狀態時，表示轉發策略正在建立中，在該狀態下，您只能執行查詢操作，不能執行其他操作。
- 當轉發策略處於 active 狀態時，表示轉發策略建立完成。
CreateForwardingRules 介面不支援在同一個全球加速執行個體內併發建立轉發策略。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ga:CreateForwardingRules

create

*Listener

acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}

*Accelerator

acs:ga:{#regionId}:{#accountId}:ga/{#acceleratorId}

無

請求參數

名稱	類型	必填	描述	樣本值
RegionId	string	是	全球加速執行個體所屬的地域 ID，僅取值：cn-hangzhou。	cn-hangzhou
ClientToken	string	否	用戶端 Token，用於保證請求的冪等性。從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 只支援 ASCII 字元。說明若您未指定，則系統自動使用 API 請求的 RequestId 作為 ClientToken 標識。每次 API 請求的 RequestId 不一樣。	02fb3da4****
AcceleratorId	string	是	全球加速執行個體 ID。	ga-bp17frjjh0udz4q****
ListenerId	string	是	監聽執行個體 ID。	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	是	轉發策略設定資訊。
	array<object>	否	轉發策略設定資訊。
ForwardingRuleName	string	否	轉發策略名稱。長度為 2~128 個英文或中文字元，必須以大小寫字母或中文開頭，可包含數字、半形句號（.）、底線（_）和短橫線（-）。	test
Priority	integer	否	轉發策略優先順序。取值範圍：1~10000。值越小表示優先順序越高。	1
RuleActions	array<object>	是	轉發動作。
	array<object>	否	轉發動作。
ForwardGroupConfig	object	否	轉發設定。說明不建議使用該參數，建議直接使用 RuleActionType 和 RuleActionValue 設定轉發動作。
ServerGroupTuples	array<object>	是	終端節點群組設定。說明不建議使用該參數，建議直接使用 RuleActionType 和 RuleActionValue 設定轉發動作。
	object	是	終端節點群組設定。說明不建議使用該參數，建議直接使用 RuleActionType 和 RuleActionValue 設定轉發動作。
EndpointGroupId	string	是	終端節點群組 ID。說明不建議使用該參數，建議直接使用 RuleActionType 和 RuleActionValue 設定轉發動作。	epg-bp1nktp3qgbcq9ih6****
Order	integer	是	轉發優先順序。說明目前無實際意義，無需設定。	20
RuleActionType	string	是	轉發動作類型。取值： ForwardGroup：轉發。 Redirect：重新導向。 FixResponse：回傳固定回應。 Rewrite：重寫。 AddHeader：寫入標頭欄位。 RemoveHeader：刪除標頭欄位。 Drop：丟棄。	ForwardGroup
RuleActionValue	string	否	轉發動作類型對應的值。根據 RuleActionType 傳入不同的 JSON 字串值。一個轉發規則最多只能有一條 ForwardGroup、Redirect、FixResponse 類型的轉發動作。Rewrite、AddHeader、RemoveHeader 類型的轉發動作順序必須在 ForwardGroup 類型的轉發動作之前。當 RuleActionType 取值為 ForwardGroup 時，該參數為虛擬終端節點群組資訊。僅支援轉發至一個虛擬終端節點群組。取值範例為`{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r**"}`，其中： `type`：取值為`endpointgroup`。 `value`：目標虛擬終端節點群組 ID。當 RuleActionType 取值為 Redirect 時，該參數為重新導向設定資訊。Redirect** 類型的轉發動作中`protocol`、`domain`、`port`、`path`、`query`不能全部為空或者預設值。取值範例為`{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" }`，其中： `protocol`：指定重新導向的通訊協定。取值為`HTTP`或`HTTPS`，不填寫預設為 `HTTP`。 `domain`：指定重新導向的網域參數。不填寫預設為空，表示保持原有網域。網域長度為 3~128 個字元，只允許包含小寫字母、數字和特殊字元`.-?=~_-+/^!$&()[]`。 `port`：指定重新導向的連接埠參數。不填寫預設為空，`HTTP 監聽`預設為`80`，`HTTPS 監聽`預設為`443`。連接埠取值範圍為`1~63335`。 `path`：指定重新導向的路徑參數。不填寫預設為空，表示保持原有路徑。路徑長度限制為 1~128 個字元。正規表達式類型的路徑，必須以波浪線（~）開頭，支援的大小寫字母、數字和特殊字元`.-_/=?~^$:()[]+`；非正規表達式類型的路徑，必須以正斜線（/）開頭，支援大小寫字母、數字和特殊字元`.-_/=?:`。 `query`：指定重新導向的查詢參數。不填寫預設為空，表示保持原有查詢。查詢字串長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和特殊字元`[]{}<>\#&`。 `code`：跳轉方式。支援`301`、`302`、`303`、`307`或`308`。當 RuleActionType 取值為 FixResponse 時，該參數為回傳固定回應設定資訊。取值範例為`{"code":"200", "type":"text/plain", "content":"dssacav" }`，其中： `code`：回應狀態碼。僅支援`2xx`、`4xx`、`5xx`數字型字串，`x`為任意數字。 `type`：回應內文類型。僅支援text/plain, text/css, text/html, application/javascript, application/json。 `content`：回應內文。回應內文長度不能超過 1000 個字元，不支援中文字元。當 RuleActionType 取值為 AddHeader 時，該參數為插入 HTTP 標頭欄位設定資訊。轉發規則中存在 AddHeader 類型的轉發動作，必須同時設定一條 ForwardGroup 類型的轉發動作。取值範例為`[{"name":"header1","type":"user-defined", "value":"value"}]`，其中： `name`：HTTP 標頭欄位名稱。名稱長度為 1~40 字元，支援大小寫字母、數字、短橫線（-）和底線（_）。AddHeader 中的 HTTP 標頭欄位名稱不能重複，也不能和 RemoveHeader 中的 HTTP 標頭欄位名稱重複。 `type`：HTTP 標頭欄位內容類型。取值範圍為`user-defined`（使用者指定）、`ref`（參考）、`system-defined`（系統定義）。 `value`：HTTP 標頭欄位內容，內容不能為空。`type`為`user-defined`（使用者指定）時，長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內的可列印字元，支援大小寫字母、數字、短橫線（-）和底線（），開頭和結尾不能為空格；`type`為`ref`（參考）時，長度為 1~128 個字元，支援大小寫字母、數字、短橫線（-）和底線（），開頭和結尾不能為空格；`type`為`system-defined`（系統定義）時，僅支援取值為`ClientSrcIp`。當 RuleActionType 取值為 RemoveHeader 時，該參數為刪除 HTTP 標頭欄位資訊。轉發規則中存在 RemoveHeader 類型的轉發動作，必須同時設定一條 ForwardGroup 類型的轉發動作。長度為 1~40 字元，支援大小寫字母、數字、短橫線（-）和底線（_）。取值範例為`["header1"]`。當 RuleActionType 取值為 Rewrite 時，該參數為重寫設定資訊。轉發規則中存在 Rewrite 類型的轉發動作，必須同時設定一條 ForwardGroup 類型的轉發動作。取值範例為`{"domain":"value1", "path":"value2", "query":"value3"}`，其中： `domain`：指定重寫的網域參數。不填寫預設為空，表示保持原有網域。網域長度為 3~128 個字元，只允許包含小寫字母、數字和特殊字元`.-?=~_-+/^!$&()[]`。 `path`：指定重寫的路徑參數。不填寫預設為空，表示保持原有路徑。路徑長度限制為 1~128 個字元。正規表達式類型的路徑，必須以波浪線（~）開頭，支援的大小寫字母、數字和特殊字元`.-_/=?~^$:()[]+`；非正規表達式類型的路徑，必須以正斜線（/）開頭，支援大小寫字母、數字和特殊字元`.-_/=?:`。 `query`：指定重寫的查詢參數。不填寫預設為空，表示保持原有查詢。查詢字串長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和特殊字元`[]{}<>\#&`。當 RuleActionType 取值為 Drop 時，該參數無需填寫。	[{"type":"endpointgroup","value":"epg-bp1l49ltx6iengvf2ks5z****"}]
RuleConditions	array<object>	是	轉發條件清單。
	array<object>	否	轉發條件清單。
HostConfig	object	否	網域設定資訊。說明不建議使用該參數，建議直接使用 RuleConditionType 和 RuleConditionValue 設定轉發條件。
Values	array	否	網域設定。說明不建議使用該參數，建議直接使用 RuleConditionType 和 RuleConditionValue 設定轉發條件。
	string	否	網域。網域長度為 3~128 個字元，允許包含字母、數字、短橫線（-）和半形句號（.），支援使用星號（）和半形問號（?）作為萬用字元。說明不建議使用該參數，建議直接使用 RuleConditionType* 和 RuleConditionValue 設定轉發條件。	example.com
PathConfig	object	否	路徑設定資訊。說明不建議使用該參數，建議直接使用 RuleConditionType 和 RuleConditionValue 設定轉發條件。
Values	array	否	路徑設定。路徑長度為 1~128 個字元，必須以正斜線（/）開頭，只允許包含字母、數字、美元符號（$）、短橫線（-）、底線（_）、半形句號（.）、加號（+）、正斜線（/）、and（&）、波浪線（~）、at（@）、半形冒號（:）、半形單引號（'），支援使用星號（）和半形問號（?）作為萬用字元。說明不建議使用該參數，建議直接使用 RuleConditionType* 和 RuleConditionValue 設定轉發條件。
	string	否	路徑設定。路徑長度為 1~128 個字元，必須以正斜線（/）開頭，只允許包含字母、數字、美元符號（$）、短橫線（-）、底線（_）、半形句號（.）、加號（+）、正斜線（/）、and（&）、波浪線（~）、at（@）、半形冒號（:）、半形單引號（'），支援使用星號（）和半形問號（?）作為萬用字元。說明不建議使用該參數，建議直接使用 RuleConditionType* 和 RuleConditionValue 設定轉發條件。	/test
RuleConditionType	string	否	轉發條件類型。取值： Host：網域。 Path：路徑。 RequestHeader：HTTP 標頭。 Query：查詢字串。 Method：HTTP 請求方法。 Cookie：Cookie。 SourceIP：來源 IP。枚舉值： Cookie : Cookie Path : 路徑。 SourceIP : 來源 IP。 Query : 查詢字串。 AIModel : AI 模型。 RequestHeader : HTTP 標頭。 Host : 網域。 Method : HTTP 請求方法。	Host
RuleConditionValue	string	否	轉發條件類型對應的值。根據 RuleConditionType 傳入不同的 JSON 字串值。當 RuleConditionType 取值為 Host 時，該參數為網域條件設定資訊。一個轉發策略內只允許建立一個網域類型轉發規則，該轉發規則內支援設定多個網域，多個網域間為「或」關係。網域長度為 3~128 個字元，允許包含字母、數字、短橫線（-）和半形句號（.），支援使用星號（）和半形問號（?）作為萬用字元。取值範例為`["www.example.com", "www.aliyun.com"]`。當 RuleConditionType* 取值為 Path 時，該參數為路徑條件設定資訊。一個轉發策略內允許建立多個路徑類型轉發規則，多個路徑類型轉發規則間為「或」關係，一個轉發路徑類型規則內支援設定多個路徑，多個路徑間為「或」關係。路徑長度為 1~128 個字元，必須以正斜線（/）開頭，只允許包含字母、數字、美元符號（$）、短橫線（-）、底線（_）、半形句號（.）、加號（+）、正斜線（/）、and（&）、波浪線（~）、at（@）、半形冒號（:）、撇號（'），支援使用星號（）和半形問號（?）作為萬用字元。取值範例為`["/a", "/b/"]`。當 RuleConditionType* 取值為 RequestHeader 時，該參數為 HTTP 標頭欄位條件設定資訊，由鍵（Key）和值（Value）組成。同一個轉發規則條件內標頭欄位值不能重複。取值範例為`[{"header1":["value1","value2"]}]`。 Key：HTTP 標頭的鍵值長度為 1~40 個字元，支援字母、數字、短橫線（-）和底線（_）。 Value：HTTP 標頭的值長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，開頭和結尾不能為空格。當 RuleConditionType 取值為 Query 時，該參數為查詢字串條件設定資訊，由鍵（Key）和值（Value）組成。取值範例為`[{"query1":["value1"]}, {"query2":["value2"]}]`。 Key：HTTP 標頭的鍵值長度為 1~100 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和`[]{}<>\;/?:@&=+,$%"^~`。 Value：HTTP 標頭的值長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和`[]{}<>\;/?:@&=+,$%"^~`。當 RuleConditionType 取值為 Method 時，該參數為請求方法設定資訊。取值範圍為 HEAD、GET、POST、OPTIONS、PUT、PATCH、DELETE。取值範例為`["GET", "OPTIONS", "POST"]`。當 RuleConditionType 取值為 Cookie 時，該參數為 Cookie 設定資訊，由鍵（Key）和值（Value）組成。取值範例為`[{"cookie1":["value1"]}, {"cookie2":["value2"]}]` Key：Cookie 的鍵值長度為 1~100 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和`#[]{}\<>&`。 Value：Cookie 的值長度為 1~128 個字元，支援 ASCII 碼值`ch >= 32 && ch < 127`範圍內可列印字元，如果是字母必須為小寫字母，不支援空格和`#[]{}\<>&`。當 RuleConditionType 取值為 SourceIP 時，該參數為來源 IP 設定資訊，支援 IP 位址，例如 1.1.XX.XX/32，或 IP 位址段，例如 2.2.XX.XX/24。一個轉發規則只允許建立一個來源 IP 規則，該轉發規則內支援設定多個來源 IP，多個 IP 之間為「或」關係。取值範例為`["1.1.XX.XX/32", "2.2.XX.XX/24"]`。	["www.example.com", "www.aliyun.com"]
RuleDirection	string	否	規則生效方向。無需設定。目前預設為 request，表示請求方向生效。	request

返回參數

名稱	類型	描述	樣本值
	object	回傳資訊清單。
ForwardingRules	array<object>	轉發策略資訊。
	object	轉發策略資訊。
ForwardingRuleId	string	轉發策略 ID。	frule-bp1dii16gu9qdvb34****
RequestId	string	請求 ID。	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF

樣本

正常返回樣本

JSON格式

{
  "ForwardingRules": [
    {
      "ForwardingRuleId": "frule-bp1dii16gu9qdvb34****"
    }
  ],
  "RequestId": "64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF"
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊
400	NotExist.Listener	The listener does not exist.
400	NotActive.Listener	The state of the listener is not active.
400	NotExist.Accelerator	The accelerated instance does not exist.
400	StateError.Accelerator	The state of the accelerated instance is invalid.
400	NotExist.BusinessRegion	The business region does not exist.
400	NotExist.BasicBandwidthPackage	You must specify the basic bandwidth package.
400	QuotaExceeded.EndPoint	The maximum number of endpoints is exceeded.
400	Exist.EndpointGroup	The endpoint group already exists.
400	NoPermission.VpcEndpoint	You are not authorized to perform the operation.
400	QuotaExceeded.ForwardingRule	The number of forwarding rule exceeds the limit.
400	SystemBusy	System busy, please try again later.
400	RepeatPathAndHost.ForwardingRule	The path and host %s are duplicated.
400	QuotaExceeded.RuleConditionConfig	The number of paths and hosts exceeds the limit.

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

變更歷史

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