Update GA Forwarding Rules with UpdateForwardingRules API - Global Accelerator - Alibaba Cloud - Global Accelerator

Updates a traffic forwarding rule.

Operation description

UpdateForwardingRules is an asynchronous operation. After a request is sent, the system returns a request ID, but the forwarding rule is not yet modified. The modification task continues to run in the background. You can call ListForwardingRules to query the status of a forwarding rule:
- If the forwarding rule is in the configuring state, the forwarding rule is being modified. In this state, you can only perform query operations.
- If the forwarding rule is in the active state, the forwarding rule is modified.
UpdateForwardingRules does not support concurrent modification of forwarding rules within the same 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:UpdateForwardingRules

update

*Listener

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

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the Global Accelerator (GA) instance. 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 token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the RequestId of the API request as the ClientToken. The RequestId may be different for each API request.	02fb3da4****
AcceleratorId	string	Yes	The ID of the Global Accelerator (GA) instance.	ga-bp17frjjh0udz4q****
ListenerId	string	Yes	The listener ID.	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	Yes	The configurations of the forwarding rules.	test
	array<object>	No	The configurations of the forwarding rules.
Priority	integer	Yes	The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates a higher priority.	1000
RuleConditions	array<object>	Yes	The forwarding conditions.
	array<object>	No	The forwarding conditions.
RuleConditionType	string	Yes	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. Specify different JSON string values based on the value of RuleConditionType. If RuleConditionType is set to Host, this parameter specifies the domain name condition. Only one domain name condition can be created in a forwarding rule. Multiple domain names can be configured in the condition, and the domain names have an OR relationship. 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. Multiple path conditions can be created in a forwarding rule, and the path conditions have an OR relationship. Multiple paths can be configured in a path condition, and the paths have an OR relationship. The path must be 1 to 128 characters in length, must start with a forward slash (/), and 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 condition, which consists of key-value pairs. Header values cannot be duplicated within the same forwarding 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, which consists of key-value pairs. 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 condition. 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 condition, which consists of key-value pairs. Example: `[{"cookie1":["value1"]}, {"cookie2":["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 SourceIP, this parameter specifies the 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. Only one source IP condition can be created in a forwarding rule. Multiple source IP addresses can be configured in the condition, and the IP addresses have an OR relationship. 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. Note This parameter is not recommended. Use RuleConditionType and RuleConditionValue to configure forwarding conditions.
	string	No	The path configuration. The path must be 1 to 128 characters in length, must start with a forward slash (/), and 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. Note* This parameter is not recommended. Use RuleConditionType and RuleConditionValue to configure forwarding 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 not recommended. Use RuleConditionType and RuleConditionValue to configure forwarding conditions.
	string	No	The domain name configuration. 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.com
RuleActions	array<object>	Yes	The forwarding actions.
	array<object>	Yes	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. Specify different JSON string values based on the value of RuleActionType. A forwarding rule can contain at most one ForwardGroup, Redirect, or FixResponse action. Rewrite, AddHeader, and RemoveHeader actions must be ordered before the ForwardGroup action. 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** 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 response body type. 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 to insert. If a forwarding rule contains an AddHeader action, a ForwardGroup 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 an AddHeader action cannot be duplicated or be the same as the HTTP header field name in a RemoveHeader action. `type`: The content type of the HTTP header field. Valid values: `user-defined` (user-specified), `ref` (reference), 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`, including 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 action, a ForwardGroup action must also be configured. The name 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 action, a ForwardGroup 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-bp1enpdcrqhl78g6r****"}]
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 not recommended. Use RuleActionType and RuleActionValue to configure forwarding actions.
	object	Yes	The endpoint group configuration. Note This parameter is not recommended. Use RuleActionType and RuleActionValue to configure forwarding actions.
EndpointGroupId	string	Yes	The endpoint group ID. Note This parameter is not recommended. Use RuleActionType and RuleActionValue to configure forwarding actions.	epg-bp1ieei9664r5nv****
ForwardingRuleId	string	Yes	The forwarding rule ID.	frule-bp1dii16gu9qdvb34****
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.
ForwardingRules	array<object>	The forwarding rule information.
	object	The forwarding rule information.
ForwardingRuleId	string	The forwarding rule ID.	frule-bp1dii16gu9qdvb34****
RequestId	string	The request ID.	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF

Examples

Success response

JSON format

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

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.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	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.
400	NotExist.BusinessRegion	The business region does not exist.	The business region does not exist.
400	NotExist.ForwardingRule	The forwarding rule %s does not exist.	The forwarding rule does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.