CreateForwardingRules - Global Accelerator - Alibaba Cloud Documentation Center

If you want to distribute and process traffic based on request attributes, such as domain names and paths, or information in requests, such as HTTP headers and cookies, you can create custom forwarding rules for a listener. The listener forwards requests based on the forwarding rules. You can call the CreateForwardingRules operation to create forwarding rules.

Operation description

Before you call this operation to create forwarding rules, we recommend that you learn how forwarding rules work and how requests are matched against forwarding rules. For more information, see Configure forwarding rules.

When you call this operation, take note of the following items:

CreateForwardingRules is an asynchronous operation. After you send a request, the system returns a forwarding rule ID and runs the task in the background. You can call the ListForwardingRules operation to query the status of a forwarding rule.
- If the forwarding rule is in the configuring state, the rule is being created. In this case, you can only perform query operations.
- If the forwarding rule is in the active state, the rule is created.
The CreateForwardingRules operation cannot be repeatedly called for the same Global Accelerator (GA) instance within a specific period of time.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
ga:CreateForwardingRules	create	Listener acs:ga:{#regionId}:{#accountId}:listener/{#listenerId} Accelerator acs:ga:{#regionId}:{#accountId}:ga/{#acceleratorId}	none	none

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The ID of the region where the GA instance is deployed. Set the value to cn-hangzhou.	cn-hangzhou
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The client token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.	02fb3da4****
AcceleratorId	string	Yes	The ID of the GA instance.	ga-bp17frjjh0udz4q****
ListenerId	string	Yes	The ID of the listener.	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	Yes	The configurations of the forwarding rules.	test
	object	Yes	The configuration of the forwarding rule.
Priority	integer	No	The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority.	1000
RuleConditions	array<object>	Yes	The forwarding conditions.
	object	No	The forwarding conditions.
RuleConditionType	string	No	The type of the forwarding condition. Valid values: Host: Requests are forwarded based on domain names. Path: Requests are forwarded based on paths. RequestHeader: Requests are forwarded based on HTTP headers. Query: Requests are forwarded based on query strings. Method: Requests are forwarded based on HTTP request methods. Cookie: Requests are forwarded based on cookies. SourceIP: Requests are forwarded based on source IP addresses.	Host
RuleConditionValue	string	No	The value of the forwarding condition. You must specify different JSON strings based on RuleConditionType. If RuleConditionType is set to Host, RuleConditionValue specifies a domain name condition. A forwarding rule can contain only one forwarding condition of the Host type. You can specify multiple domain names in a forwarding condition. The relationship between multiple domain names is OR. The domain name must be 3 to 128 characters in length, and can contain letters, digits, hyphens (-), and periods (.). You can use asterisks () and question marks (?) as wildcard characters. Example: `["www.example.com", "www.aliyun.com"]`. If RuleConditionType* is set to Path, RuleConditionValue specifies a path condition. A forwarding rule can contain multiple forwarding conditions of the Path type. The relationship between multiple path conditions is OR. You can specify multiple paths in a forwarding condition. The relationship between multiple paths is OR. The path must be 1 to 128 characters in length, and must start with a forward slash (/). The path can contain letters, digits, and the following special characters: $ - _ . + / & ~ @ : '. Supported wildcard characters are asterisks () and question marks (?). Example: `["/a", "/b/"]`. If RuleConditionType* is set to RequestHeader, RuleConditionValue specifies an HTTP header condition. An HTTP header consists of a key and a value. The header values in a forwarding condition must be unique. Example: `[{"header1":["value1","value2"]}]`. Key: The key of an HTTP header must be 1 to 40 characters in length and can contain letters, digits, hyphens (-), and underscores (_). Value: The value of an HTTP header must be 1 to 128 characters in length and can contain printable characters whose ASCII values `are larger than or equal to 32 and smaller than 127`. The value cannot start or end with a space. If RuleConditionType is set to Query, RuleConditionValue specifies a query string condition. A query string consists of a key and a value. Example: `[{"query1":["value1"]}, {"query2":["value2"]}]`. Key: The key must be 1 to 100 characters in length and can contain printable characters whose ASCII values `are larger than or equal to 32 and smaller than 127`, excluding uppercase letters, spaces, and the following special characters: `[ ] { } < > \ ; / ? : @ & = + , $ % " ^ ~`. Value: The value must be 1 to 128 characters in length and can contain printable characters whose ASCII values `are larger than or equal to 32 and smaller than 127`, excluding uppercase letters, spaces, and the following special characters: `[ ] { } < > \ ; / ? : @ & = + , $ % " ^ ~`. If RuleConditionType is set to Method, RuleConditionValue specifies an HTTP method condition. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE. Example: `["GET", "OPTIONS", "POST"]`. If RuleConditionType is set to Cookie, RuleConditionValue specifies a cookie condition. A cookie consists of a key and a value. Example: `[{"cookie1":["value1"]}, {"cookie2":["value2"]}]`. Key: The key of a cookie must be 1 to 100 characters in length and can contain printable characters whose ASCII values `are larger than or equal to 32 and smaller than 127`, excluding uppercase letters, spaces, and the following special characters: `# [ ] { } \ < > &`. Value: The value of a cookie must be 1 to 128 characters in length and can contain printable characters whose ASCII values `are larger than or equal to 32 and smaller than 127`, excluding uppercase letters, spaces, and the following special characters: `# [ ] { } \ < > &`. If RuleConditionType is set to SourceIP, RuleConditionValue specifies a source IP address condition. IP addresses, such as 1.1.XX.XX/32, and CIDR blocks, such as 2.2.XX.XX/24, are supported. A forwarding rule can contain only one forwarding condition of the SourceIP type. You can specify multiple source IP addresses or CIDR blocks in a forwarding condition. The relationship between multiple IP addresses or CIDR blocks is OR. Example: `["1.1.XX.XX/32", "2.2.XX.XX/24"]`.	["www.example.com", "www.aliyun.com"]
PathConfig	object	No	The configuration of the path. Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
Values	array	No	The path. The path must be 1 to 128 characters in length, and must start with a forward slash (/). The path can contain letters, digits, and the following special characters: $ - _ . + / & ~ @ : '. Supported wildcard characters are asterisks () and question marks (?). Note* We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
	string	No	The path. The path must be 1 to 128 characters in length, and must start with a forward slash (/). The path can contain letters, digits, and the following special characters: $ - _ . + / & ~ @ : '. Supported wildcard characters are asterisks () and question marks (?). Note* We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.	/test
HostConfig	object	No	The configuration of the domain name. Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
Values	array	No	The domain name. Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
	string	No	The domain name. The domain name must be 3 to 128 characters in length, and can contain letters, digits, hyphens (-), and periods (.). You can use asterisks () and question marks (?) as wildcard characters. Note* We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.	example.com
RuleActions	array<object>	Yes	The configurations of the forwarding action.
	object	No	The configurations of the forwarding action.
Order	integer	Yes	The forwarding priority. Note This parameter does not take effect. Ignore this parameter.	20
RuleActionType	string	Yes	The type of the forwarding action. Valid values: ForwardGroup: forwards a request. Redirect: redirects a request. FixResponse: returns a fixed response. Rewrite: rewrites a request. AddHeader: adds a header to a request. RemoveHeaderConfig: deletes the header from a request. Drop: drops a request.	ForwardGroup
RuleActionValue	string	No	The value of the forwarding action. You must specify different JSON strings based on the RuleActionType parameter. A forwarding rule can contain only one forwarding action whose type is ForwardGroup, Redirect, or FixResponse. You must specify a forwarding action whose type is Rewrite, AddHeader, or RemoveHeader before a forwarding action whose type is ForwardGroup. If RuleActionType is set to ForwardGroup, this parameter specifies the information of a virtual endpoint group. You can forward requests to only one virtual endpoint group. Example: `{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r**"}`. `type`: Set this parameter to `endpointgroup`. `value`: Set this parameter to the ID of a virtual endpoint group. If RuleActionType is set to Redirect, this parameter specifies redirecting configurations. You cannot leave all the following parameters empty or use the default values for all the following parameters for a forwarding action whose type is Redirect*: `protocol`, `domain`, `port`, `path`, and `query`. Example: `{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" }`. `protocol`: the protocol of requests after the requests are redirected. Valid values: `${protocol}` (default), `HTTP`, and `HTTPS`. `domain`: the domain name to which requests are redirected. Default value: `${host}`. You can also enter a domain name. The domain name must be 3 to 128 characters in length, and can contain only letters, digits, and the following special characters: `. - ? = ~ _ - + / ^ ! $ & \| ( ) [ ]`. `port`: the port to which requests are redirected. Default value: `${port}`. You can enter a port number that ranges from 1 to 63335. `path`: the path to which requests are redirected. Default value: `${path}`. The path must be 1 to 128 characters in length. To use a regular expression, the path can contain letters, digits, and the following special characters: `. - _ / = ? ~ ^ * $ : ( ) [ ] +`. The path must start with a tilde (~). If you do not want to use a regular expression, the path can contain letters, digits, and the following special characters: `. - _ / = ? :`. The path must start with a forward slash (/). `query`: the query string to which requests are redirected. Default value: `${query}`. You can also specify a query string. The query string must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are `greater than or equal to 32 and smaller than 127`. The query string cannot contain uppercase letters, space characters, or the following special characters: `[ ] { } < > # &`. `code`: the redirect code. Valid values: `301`, `302`, `303`, `307`, and `308`. If RuleActionType is set to FixResponse, this parameter specifies a fixed response. Example: `{"code":"200", "type":"text/plain", "content":"dssacav" }`. `code`: the HTTP response status code. The response status code must be one of the following numeric strings: `2xx`, `4xx`, and `5xx`. The letter `x` is a digit. `type`: the type of the response content. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. `content`: the response content. The response content cannot exceed 1,000 characters in length, and does not support Chinese characters. If RuleActionType is set to AddHeader, this parameter specifies an HTTP header to be added. If a forwarding rule contains a forwarding action whose type is AddHeader, you must specify another forwarding action whose type is ForwardGroup. Example: `[{"name":"header1","type":"userdefined", "value":"value"}]`. `name`: the name of the HTTP header. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). The name of the HTTP header specified by AddHeader must be unique and cannot be the same as the name of the HTTP header specified by RemoveHeader. `type`: the content type of the HTTP header. Valid values: `user-defined`, `ref`, and `system-defined`. `value`: the content of the HTTP header. You cannot leave this parameter empty. If you set `type` to `user-defined`, the content must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are `greater than or equal to 32 and smaller than 127`. The content can contain letters, digits, hyphens (-), and underscores (_). The content cannot start or end with a space character. If you set `type` to `ref`, the content must be 1 to 128 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). The content cannot start or end with a space character. If you set `type` to `system-defined`, only `ClientSrcIp` is supported. If RuleActionType is set to RemoveHeader, this parameter specifies an HTTP header to be removed. If a forwarding rule contains a forwarding action whose type is RemoveHeader, you must specify another forwarding action whose type is ForwardGroup. The header must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Example: `["header1"]`. If RuleActionType is set to Rewrite, this parameter specifies the rewriting configuration. If a forwarding rule contains a forwarding action whose type is Rewrite, you must specify another forwarding action whose type is ForwardGroup. Example: `{"domain":"value1", "path":"value2", "query":"value3"}`. `domain`: the domain name to which requests are redirected. Default value: `${host}`. You can also enter a domain name. The domain name must be 3 to 128 characters in length, and can contain only lowercase letters, digits, and the following special characters: `. - ? = ~ _ - + / ^ * ! $ & \| ( ) [ ]`. `path`: the path to which requests are redirected. Default value: `${path}`. The path must be 1 to 128 characters in length. To use a regular expression, the path can contain letters, digits, and the following special characters: `. - _ / = ? ~ ^ * $ : ( ) [ ] +`. The path must start with a tilde (~). If you do not want to use a regular expression, the path can contain letters, digits, and the following special characters: `. - _ / = ? :`. The path must start with a forward slash (/). `query`: the query string to which requests are redirected. Default value: `${query}`. You can also specify a query string. The query string must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are `greater than or equal to 32 and smaller than 127`. The query string cannot contain uppercase letters, space characters, or the following special characters: `[ ] { } < > # &`. If RuleActionType is set to Drop, you do not need to specify this parameter.	[{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}]
ForwardGroupConfig	object	No	The forwarding configurations. Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding conditions.
ServerGroupTuples	array<object>	Yes	The configurations of an endpoint group. Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding conditions.
	object	Yes	The configurations of an endpoint group. Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding conditions.
EndpointGroupId	string	Yes	The ID of the endpoint group. Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding conditions.	epg-bp1ieei9664r5nv****
ForwardingRuleName	string	No	The name of the forwarding rule. The name must be 2 to 128 characters in length, and can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter.	test
RuleDirection	string	No	The direction in which the rule takes effect. You do not need to specify this parameter. By default, this parameter is set to request, which specifies that the rule takes effect on requests.	request

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF
ForwardingRules	array<object>	The forwarding rules.
ForwardingRules	object	The forwarding rules.
ForwardingRuleId	string	The ID of the forwarding rule.	frule-bp1dii16gu9qdvb34****

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status code	Error code	Error message	Description
400	NotExist.Listener	The listener does not exist.	The listener does not exist.
400	NotActive.Listener	The state of the listener is not active.	The listener is unstable.
400	NotExist.Accelerator	The accelerated instance does not exist.	The GA instance does not exist.
400	StateError.Accelerator	The state of the accelerated instance is invalid.	The status of the GA instance is invalid.
400	NotExist.BusinessRegion	The business region does not exist.	The business region does not exist.
400	NotExist.BasicBandwidthPackage	You must specify the basic bandwidth package.	You must specify the basic bandwidth package.
400	QuotaExceeded.EndPoint	The maximum number of endpoints is exceeded.	The maximum number of endpoints is exceeded.
400	Exist.EndpointGroup	The endpoint group already exists.	The endpoint group already exists.
400	NoPermission.VpcEndpoint	You are not authorized to perform the operation.	The user does not have permissions to create service linked roles. Contact the Alibaba Cloud account owner or the permission administrator to grant the current user AliyunGlobalAccelerationFullAccess or create custom permission policies for service linked role. The following content describes the detailed information about custom permission policies: ServiceName: vpcendpoint.ga.aliyuncs.com. Service linked role name: AliyunServiceRoleForGaVpc. Endpoint Permission: ram:CreateServiceLinkedRole.
400	QuotaExceeded.ForwardingRule	The number of forwarding rule exceeds the limit.	The number of forwarding rule exceeds the limit.
400	QuotaExceeded.RuleConditionConfig	The number of path and host exceeds the limit.	-
400	RepeatPathAndHost.ForwardingRule	path and host %s repeat	-

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-04-22	The Error code has changed	View Change Details
2023-04-20	The Error code has changed	View Change Details