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

If you need to distribute traffic based on request attributes such as the domain name, path, HTTP headers, and cookies, you can create custom forwarding rules for a listener. The listener evaluates incoming requests against these rules and performs different forwarding actions. To create forwarding rules, call the CreateForwardingRules API.

Operation description

Before you call this API, you should understand how forwarding rules work and their matching conditions. For more information, see Forwarding rules.

When you call this API, note the following:

The CreateForwardingRules API is asynchronous. After the call is made, the system returns a forwarding rule ID, but the rule is still being created. You can call ListForwardingRules to query the status of the forwarding rule:
- If a forwarding rule is in the configuring status, it is still being created, and you can only perform query operations.
- If a forwarding rule is in the active status, the rule has been created.
You cannot use the CreateForwardingRules API to create forwarding rules concurrently for the same Global Accelerator 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 ID of the region where the Global Accelerator instance is deployed. The only valid value is cn-hangzhou.	cn-hangzhou
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can generate a client token from your client and make sure that the client 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 RequestId of the request as the ClientToken. The RequestId of each request is different.	02fb3da4****
AcceleratorId	string	Yes	The ID of the Global Accelerator instance.	ga-bp17frjjh0udz4q****
ListenerId	string	Yes	The ID of the listener.	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	Yes	The forwarding rule configurations.	test
	array<object>	No	A forwarding rule configuration.
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 rule conditions.
	array<object>	No	A rule condition.
RuleConditionType	string	No	The type of the rule condition. Valid values: Host: Matches requests by domain name. Path: Matches requests by path. RequestHeader: Matches requests by HTTP header. Query: Matches requests by query string. Method: Matches requests by HTTP method. Cookie: Matches requests by cookie. SourceIP: Matches requests by source IP address.	Host
RuleConditionValue	string	No	The value of the rule condition. This is a JSON-formatted string whose structure depends on the specified RuleConditionType. If RuleConditionType is set to Host, this parameter specifies the domain name conditions. A forwarding rule can have only one Host rule condition. This rule condition can contain multiple domain names, which are evaluated with a logical OR. 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. Example: `["www.example.com", "www.aliyun.com"]`. If RuleConditionType* is set to Path, this parameter specifies the path conditions. A forwarding rule can have multiple Path rule conditions, which are evaluated with a logical OR. Each path rule condition can contain multiple paths, which are also evaluated with a logical OR. 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. Example: `["/a", "/b/"]`. If RuleConditionType* is set to RequestHeader, this parameter specifies the HTTP header conditions. The value is a key-value pair. The header values within the same rule condition must be unique. Example: `[{"header1":["value1","value2"]}]`. Key: The HTTP header key must be 1 to 40 characters long and can contain letters, digits, hyphens (-), and underscores (_). Value: The HTTP header value must be 1 to 128 characters long and contain only printable characters within the ASCII 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 conditions. The value is a key-value pair. Example: `[{"query1":["value1"]}, {"query2":["value2"]}]`. Key: The key must be 1 to 100 characters long and contain only printable characters within the ASCII 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 long and contain only printable characters within the ASCII 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 HTTP method conditions. 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 conditions. The value is a key-value pair. Example: `[{"cookie1":["value1"]}, {"cookie2":["value2"]}]` Key: The cookie key must be 1 to 100 characters long and contain only printable characters within the ASCII range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following characters are not supported: `#[]{}\<>&`. Value: The cookie value must be 1 to 128 characters long and contain only printable characters within the ASCII 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 conditions. You can specify IP addresses, for example, `1.1.XX.XX/32`, or CIDR blocks, for example, `2.2.XX.XX/24`. A forwarding rule can have only one SourceIP rule condition. This rule condition can contain multiple source IP addresses, which are evaluated with a logical 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 deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule 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 deprecated. We recommend that you use RuleConditionType and RuleConditionValue to configure rule 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 rule actions.
	array<object>	No	A rule action.
Order	integer	Yes	The priority of the action. Note This parameter is not in use and can be ignored.	20
RuleActionType	string	Yes	The type of the rule action. Valid values: ForwardGroup: Forwards requests. Redirect: Redirects requests. FixResponse: Returns a fixed response. Rewrite: Rewrites requests. AddHeader: Adds a header. RemoveHeader: Removes a header. Drop: Drops requests.	ForwardGroup
RuleActionValue	string	No	The value for the rule action. This is a JSON-formatted string whose structure depends on the specified RuleActionType. A forwarding rule can have at most one action of type ForwardGroup, Redirect, or FixResponse. Actions of type Rewrite, AddHeader, and RemoveHeader must be specified before a ForwardGroup action. If RuleActionType is set to ForwardGroup, this parameter specifies the endpoint group. You can forward requests to only one endpoint group. Example: `{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r**"}`, where: `type`: Set the value to `endpointgroup`. `value`: The ID of the target endpoint group. If RuleActionType is set to Redirect*, this parameter specifies the redirect configuration. At least one of the `protocol`, `domain`, `port`, `path`, or `query` fields must be set to a value other than its default. Example: `{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" }`, where: `protocol`: The protocol for the redirect. Valid values: `${protocol}` (default), `HTTP`, and `HTTPS`. `domain`: The domain name for the redirect. The default value is `${host}`. You can also specify another domain name. A domain name must be 3 to 128 characters long and can contain only lowercase letters, digits, and the following special characters: `.-=~_-+/^!$&()[]?`. `port`: The port for the redirect. The default value is `${port}`. You can also specify a port number. Valid values: 1 to 63335. `path`: The path for the redirect. The default value is `${path}`. The path must be 1 to 128 characters long. For a regular expression path, it must start with a tilde (~) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?~^$:()[]+`. For a non-regular expression path, it must start with a forward slash (/) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=:?`. `query`: The query string for the redirect. The default value is `${query}`. You can also specify another query string. The query string must be 1 to 128 characters long and contain only printable characters within the ASCII range of `ch >= 32 && ch < 127`. Letters must be lowercase. Spaces and the following special characters are not supported: `[]{}<>\#&`. `code`: The 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. The value must be a numeric string in the `2xx`, `4xx`, or `5xx` format, 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 content of the response body. The content cannot exceed 1,000 characters and does not support Chinese characters. If RuleActionType is set to AddHeader, this parameter specifies the configuration for adding an HTTP header. If a forwarding rule contains an AddHeader action, it must also contain a ForwardGroup action. Example: `[{"name":"header1","type":"user-defined", "value":"value"}]`, where: `name`: The name of the HTTP header. The name must be 1 to 40 characters long and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). The header names in AddHeader actions must be unique and cannot be the same as any header name in a RemoveHeader action. `type`: The type of the header value. Valid values: `user-defined`, `ref` (reference), and `system-defined`. `value`: The content of the HTTP header. This field cannot be empty. If `type` is `user-defined`, the value must be 1 to 128 characters long and contain only printable characters within the ASCII range of `ch >= 32 && ch < 127`. The value can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_), and cannot start or end with a space. If `type` is `ref`, the value must be 1 to 128 characters long and can contain uppercase and lowercase letters, digits, hyphens (-), and underscores (_). The value cannot start or end with a space. If `type` is `system-defined`, the only valid value is `ClientSrcIp`. If RuleActionType is set to RemoveHeader, this parameter specifies the HTTP headers to remove. If a forwarding rule contains a RemoveHeader action, it must also contain a ForwardGroup action. The value must be 1 to 40 characters long 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 action, it must also contain a ForwardGroup action. Example: `{"domain":"value1", "path":"value2", "query":"value3"}`, where: `domain`: The domain name to rewrite. The default value is `${host}`. You can also specify another domain name. A domain name must be 3 to 128 characters long and can contain only lowercase letters, digits, and the following special characters: `.-=~_-+/^!$&()[]?`. `path`: The path to rewrite. The default value is `${path}`. The path must be 1 to 128 characters long. For a regular expression path, it must start with a tilde (~) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=?~^$:()[]+`. For a non-regular expression path, it must start with a forward slash (/) and can contain uppercase and lowercase letters, digits, and the following special characters: `.-_/=:?`. `query`: The query string to rewrite. The default value is `${query}`. You can also specify another query string. The query string must be 1 to 128 characters long and contain only printable characters within the ASCII 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, you do not need to specify a value for this parameter.	[{"type":"endpointgroup","value":"epg-bp1l49ltx6iengvf2ks5z****"}]
ForwardGroupConfig	object	No	The forwarding configuration. Note This parameter is deprecated. We recommend that you use RuleActionType and RuleActionValue to configure rule 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	The name of the forwarding rule. The name must be 2 to 128 characters long. It must start with a letter or a Chinese character, and can contain letters, Chinese characters, digits, periods (.), underscores (_), and hyphens (-).	test
RuleDirection	string	No	The direction in which the rule takes effect. This parameter does not need to be configured. By default, this parameter is set to request, which indicates that the rule applies to requests.	request

Response elements

Element	Type	Description	Example
	object	The response object.
RequestId	string	The request ID.	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF
ForwardingRules	array<object>	The details of the forwarding rules.
	object	The details of the forwarding rules.
ForwardingRuleId	string	The forwarding rule ID.	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.