Create Custom Forwarding Rules via API - Global Accelerator - Alibaba Cloud - Global Accelerator

Creates forwarding rules for a listener. If your business needs to distribute and process traffic based on request attributes (such as domain names and paths) or data contained in requests (such as HTTP headers and cookies), you can customize forwarding rules for a listener. The listener performs different forwarding actions on access requests based on the forwarding rules.

Operation description

Before you invoke this operation to create forwarding rules, we recommend that you understand the principles and matching rules of forwarding rules. For more information, see Forwarding rules.

Take note of the following items when you invoke this operation:

CreateForwardingRules is an asynchronous operation. After you send a request, the system returns a forwarding rule ID but the forwarding rule is not yet created. The creation task continues to run in the background. You can invoke ListForwardingRules to query the status of the forwarding rule:
- If the forwarding rule is in the configuring state, the forwarding rule is being created. In this state, you can only execute query operations.
- If the forwarding rule is in the active state, the forwarding rule is created.
CreateForwardingRules does not support concurrent creation of forwarding rules within the same Alibaba Cloud Global Accelerator (GA) instance.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ga:CreateForwardingRules

create

*Listener

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

*Accelerator

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

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the Alibaba Cloud Global Accelerator (GA) instance. Set the value to ap-southeast-1.	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 token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the RequestId value as the ClientToken value. The RequestId value is different for each API request.	02fb3da4****
AcceleratorId	string	Yes	The instance ID of the Alibaba Cloud Global Accelerator (GA).	ga-bp17frjjh0udz4q****
ListenerId	string	Yes	The instance ID of the listener.	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	Yes	The configurations of the forwarding rule.	test
	array<object>	No	The configurations of the forwarding rule.
Priority	integer	No	The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates a higher priority.	1
RuleConditions	array<object>	Yes	The list of forwarding conditions.
	array<object>	No	The list of forwarding conditions.
RuleConditionType	string	No	The type of the forwarding condition. Valid values: Host: domain name. Path: path. RequestHeader: HTTP header. Query: query string. Method: HTTP request method. Cookie: cookie. SourceIP: source IP address.	Host
RuleConditionValue	string	No	The value that corresponds to the forwarding condition type. Pass in different JSON string values based on the value of RuleConditionType. If RuleConditionType is set to Host, this parameter specifies the domain name condition configuration. Only one domain name-type forwarding rule can be created in a forwarding policy. The forwarding rule supports multiple domain names, and 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 (.). Asterisks () and question marks (?) are supported as wildcard characters. Example: `["www.example.com", "www.aliyun.com"]`. If RuleConditionType* is set to Path, this parameter specifies the path condition configuration. Multiple path-type forwarding rules can be created in a forwarding policy, and the relationship between multiple path-type forwarding rules is OR. A path-type forwarding rule supports multiple paths, and 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 only letters, digits, dollar signs ($), hyphens (-), underscores (_), periods (.), plus signs (+), forward slashes (/), ampersands (&), tildes (~), at signs (@), colons (:), and apostrophes ('). Asterisks () and question marks (?) are supported as wildcard characters. Example: `["/a", "/b/"]`. If RuleConditionType* is set to RequestHeader, this parameter specifies the HTTP header field condition configuration, which consists of a key and a value. Header field values cannot be duplicated within the same forwarding rule condition. Example: `[{"header1":["value1","value2"]}]`. Key: The key of the HTTP header must be 1 to 40 characters in length and can contain letters, digits, hyphens (-), and underscores (_). Value: The value of the HTTP header must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. The value cannot start or end with a space. If RuleConditionType is set to Query, this parameter specifies the query string condition configuration, which 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 ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following characters are not supported: `[]{}<>\;/?:@&=+,$%"^~`. Value: The value must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following characters are not supported: `[]{}<>\;/?:@&=+,$%"^~`. If RuleConditionType is set to Method, this parameter specifies the request method configuration. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE. Example: `["GET", "OPTIONS", "POST"]`. If RuleConditionType is set to Cookie, this parameter specifies the cookie configuration, which consists of a key and a value. Example: `[{"cookie1":["value1"]}, {"cookie2":["value2"]}]`. Key: The key of the cookie must be 1 to 100 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following characters are not supported: `#[]{}\<>&`. Value: The value of the cookie must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following characters are not supported: `#[]{}\<>&`. If RuleConditionType is set to SourceIP, this parameter specifies the source IP address configuration. IP addresses such as 1.1.XX.XX/32 and CIDR blocks such as 2.2.XX.XX/24 are supported. Only one source IP rule can be created in a forwarding rule. The forwarding rule supports multiple source IP addresses, and the relationship between multiple IP addresses is OR. Example: `["1.1.XX.XX/32", "2.2.XX.XX/24"]`.	["www.example.com", "www.aliyun.com"]
PathConfig	object	No	The path configuration. Note This parameter is not recommended. Use RuleConditionType and RuleConditionValue to configure forwarding conditions.
Values	array	No	The path configuration. A path must be 1 to 128 characters long and must start with a forward slash (/). It can contain letters, digits, dollar signs ($), hyphens (-), underscores (_), periods (.), plus signs (+), forward slashes (/), ampersands (&), tildes (~), at signs (@), colons (:), and apostrophes ('). You can use asterisks () and question marks (?) as wildcards. Note* This parameter is deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule conditions.
	string	No	The path configuration. A path must be 1 to 128 characters long and must start with a forward slash (/). It can contain letters, digits, dollar signs ($), hyphens (-), underscores (_), periods (.), plus signs (+), forward slashes (/), ampersands (&), tildes (~), at signs (@), colons (:), and apostrophes ('). You can use asterisks () and question marks (?) as wildcards. Note* This parameter is deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule conditions.	/test
HostConfig	object	No	The domain name configuration. Note This parameter is not recommended. Use RuleConditionType and RuleConditionValue to configure forwarding conditions.
Values	array	No	The domain name configuration. Note This parameter is deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule conditions.
	string	No	The domain name. A domain name must be 3 to 128 characters long and can contain letters, digits, hyphens (-), and periods (.). You can use asterisks () and question marks (?) as wildcards. Note* This parameter is deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule conditions.	example.com
RuleActions	array<object>	Yes	The forwarding actions.
	array<object>	No	The forwarding actions.
Order	integer	Yes	The forwarding priority. Note This parameter is not used. You do not need to configure it.	20
RuleActionType	string	Yes	The type of the forwarding action. Valid values: ForwardGroup: forwards requests. Redirect: redirects requests. FixResponse: returns a fixed response. Rewrite: rewrites requests. AddHeader: adds a header field. RemoveHeader: removes a header field. Drop: drops requests.	ForwardGroup
RuleActionValue	string	No	The value that corresponds to the forwarding action type. Pass in different JSON string values based on the value of RuleActionType. A forwarding rule can contain at most one forwarding action of the ForwardGroup, Redirect, or FixResponse type. Forwarding actions of the Rewrite, AddHeader, and RemoveHeader types must be placed before the forwarding action of the ForwardGroup type. If RuleActionType is set to ForwardGroup, this parameter specifies the virtual endpoint group information. Only one virtual endpoint group is supported. Example: `{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r**"}`, where: `type`: Set the value to `endpointgroup`. `value`: The ID of the destination virtual endpoint group. If RuleActionType is set to Redirect, this parameter specifies the redirect configuration. In a Redirect** forwarding action, `protocol`, `domain`, `port`, `path`, and `query` cannot all be empty or set to default values. Example: `{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" }`, where: `protocol`: The redirect protocol. Valid values: `HTTP` and `HTTPS`. Default value: `HTTP`. `domain`: The redirect domain name. If this parameter is left empty, the original domain name is retained. The domain name must be 3 to 128 characters in length and can contain only lowercase letters, digits, and the following special characters: `.-?=~_-+/^!$&()[]`. `port`: The redirect port. If this parameter is left empty, the default port is used. The default port is `80` for `HTTP listeners` and `443` for `HTTPS listeners`. Valid values: `1` to `63335`. `path`: The redirect path. If this parameter is left empty, the original path is retained. The path must be 1 to 128 characters in length. A regular expression path must start with a tilde (~) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?~^$:()[]+`. A non-regular expression path must start with a forward slash (/) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?:`. `query`: The redirect query parameter. If this parameter is left empty, the original query string is retained. The query string must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following special characters are not supported: `[]{}<>\#&`. `code`: The HTTP redirect code. Valid values: `301`, `302`, `303`, `307`, and `308`. If RuleActionType is set to FixResponse, this parameter specifies the fixed response configuration. Example: `{"code":"200", "type":"text/plain", "content":"dssacav" }`, where: `code`: The response status code. Only numeric strings in the format of `2xx`, `4xx`, and `5xx` are supported, where `x` is any digit. `type`: The content type of the response body. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. `content`: The response body. The response body cannot exceed 1,000 characters in length and does not support Chinese characters. If RuleActionType is set to AddHeader, this parameter specifies the HTTP header field insertion configuration. If a forwarding rule contains an AddHeader forwarding action, a ForwardGroup forwarding action must also be configured. Example: `[{"name":"header1","type":"user-defined", "value":"value"}]`, where: `name`: The name of the HTTP header field. The name must be 1 to 40 characters in length and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). The HTTP header field name in AddHeader cannot be duplicated or the same as the HTTP header field name in RemoveHeader. `type`: The content type of the HTTP header field. Valid values: `user-defined`, `ref`, and `system-defined`. `value`: The content of the HTTP header field. The content cannot be empty. If `type` is set to `user-defined`, the value must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`, uppercase and lowercase letters, digits, hyphens (-), and underscores (_). The value cannot start or end with a space. If `type` is set to `ref`, the value must be 1 to 128 characters in length and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). The value cannot start or end with a space. If `type` is set to `system-defined`, only `ClientSrcIp` is supported. If RuleActionType is set to RemoveHeader, this parameter specifies the HTTP header field to delete. If a forwarding rule contains a RemoveHeader forwarding action, a ForwardGroup forwarding action must also be configured. The value must be 1 to 40 characters in length and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). Example: `["header1"]`. If RuleActionType is set to Rewrite, this parameter specifies the rewrite configuration. If a forwarding rule contains a Rewrite forwarding action, a ForwardGroup forwarding action must also be configured. Example: `{"domain":"value1", "path":"value2", "query":"value3"}`, where: `domain`: The rewrite domain name. If this parameter is left empty, the original domain name is retained. 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 rewrite path. If this parameter is left empty, the original path is retained. The path must be 1 to 128 characters in length. A regular expression path must start with a tilde (~) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?~^$:()[]+`. A non-regular expression path must start with a forward slash (/) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?:`. `query`: The rewrite query parameter. If this parameter is left empty, the original query string is retained. The query string must be 1 to 128 characters in length and can contain printable ASCII characters in the range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following special characters are not supported: `[]{}<>\#&`. If RuleActionType is set to Drop, this parameter does not need to be specified.	[{"type":"endpointgroup","value":"epg-bp1l49ltx6iengvf2ks5z****"}]
ForwardGroupConfig	object	No	The forwarding configuration. Note This parameter is not recommended. Use RuleActionType and RuleActionValue to configure forwarding actions.
ServerGroupTuples	array<object>	Yes	The endpoint group configuration. Note This parameter is deprecated. We recommend that you use RuleActionType and RuleActionValue to configure rule actions.
	object	Yes	The endpoint group configuration. Note This parameter is deprecated. We recommend that you use RuleActionType and RuleActionValue to configure rule actions.
EndpointGroupId	string	Yes	The ID of the endpoint group. Note This parameter is deprecated. We recommend that you use RuleActionType and RuleActionValue to configure rule actions.	epg-bp1nktp3qgbcq9ih6****
ForwardingRuleName	string	No	Policy Name of the forwarding rule. Policy Name must be 2 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). Policy Name must start with a letter or Chinese character.	test
RuleDirection	string	No	The direction in which the rule takes effect. You do not need to configure this parameter. The default value is request, which indicates that the rule takes effect on requests.	request

Response elements

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

Examples

Success response

JSON format

{
  "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	SystemBusy	System busy, please try again later.
400	RepeatPathAndHost.ForwardingRule	The path and host %s are duplicated.	The path and host are duplicated.
400	QuotaExceeded.RuleConditionConfig	The number of paths and hosts exceeds the limit.	The number of paths and hosts exceeds the limit.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.