All Products
Search
Document Center

Global Accelerator:UpdateForwardingRules

Last Updated:Mar 26, 2024

Updates a forwarding rule.

Operation description

  • UpdateForwardingRules is an asynchronous operation. After a request is sent, the system returns a request 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, it indicates that the forwarding rule is being modified. In this case, you can perform only query operations.
    • If the forwarding rule is in the active state, it indicates that the forwarding rule is modified.
  • The UpdateForwardingRules operation holds an exclusive lock on the Global Accelerator (GA) instance. While the operation is in progress, you cannot call the same operation in the same Alibaba Cloud account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

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.
OperationAccess levelResource typeCondition keyAssociated operation
ga:UpdateForwardingRulesWrite
  • Listener
    acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the GA instance. Set the value to cn-hangzhou.

cn-hangzhou
ClientTokenstringNo

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 request ID as the client token. The request ID may be different for each request.
02fb3da4****
AcceleratorIdstringYes

The GA instance ID.

ga-bp17frjjh0udz4q****
ListenerIdstringYes

The listener ID.

lsr-bp1s0vzbi5bxlx5****
ForwardingRulesobject []Yes

The configurations of the forwarding rules.

test
PriorityintegerYes

The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value specifies a higher priority.

1000
RuleConditionsobject []Yes

The forwarding conditions.

RuleConditionTypestringYes

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
RuleConditionValuestringNo

The value of the forwarding condition. You must specify different JSON strings based on the value of RuleConditionType.

  • If you set RuleConditionType to Host, this parameter 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 (.). Supported wildcard characters are asterisks (*) and question marks (?). Example: ["www.example.com", "www.aliyun.com"].

  • If RuleConditionType is set to Path, this parameter 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 you set RuleConditionType to RequestHeader, this parameter specifies an HTTP header condition that consists of key-value pairs. 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 greater than or equal to 32 and less than 127. The value cannot start or end with a space character.
  • If you set RuleConditionType to Query, this parameter specifies a query string condition that consists of key-value pairs. Example: [{"query1":["value1"]}, {"query2":["value2"]}].

    • Key: The key of an HTTP header must be 1 to 100 characters in length, and can contain printable characters whose ASCII values are greater than or equal to 32 and less than 127. The key cannot contain uppercase letters, space characters, or the following special characters: [ ] { } < > \ ; / ? : @ & = + , $ % | " ^ ~.
    • Value: The value of an HTTP header must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are greater than or equal to 32 and less than 127. The value cannot contain uppercase letters, space characters, or the following special characters: [ ] { } < > \ ; / ? : @ & = + , $ % | " ^ ~.
  • If you set RuleConditionType to Method, this parameter specifies an HTTP request method condition. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE. Example: ["GET", "OPTIONS", "POST"].

  • If you set RuleConditionType to Cookie, this parameter specifies a cookie condition that consists of key-value pairs. 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 greater than or equal to 32 and less than 127. The key cannot contain uppercase letters, space characters, or 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 greater than or equal to 32 and less than 127. The value cannot contain uppercase letters, space characters, or the following special characters: # [ ] { } \ | < > &.
  • If you set RuleConditionType to SourceIP, this parameter specifies a source IP address condition. You can specify IP addresses, such as 1.1.XX.XX/32. You can also specify CIDR blocks, such as 2.2.XX.XX/24. A forwarding rule can contain only one forwarding condition whose type is SourceIP. You can specify multiple source IP addresses in a forwarding condition. The relationship between multiple source IP addresses is OR. Example: ["1.1.XX.XX/32", "2.2.XX.XX/24"].

["www.example.com", "www.aliyun.com"]
PathConfigobjectNo

The path configuration.

Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
ValuesarrayNo

The path configuration.

Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
stringNo

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
HostConfigobjectNo

The domain name configuration.

Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
ValuesarrayNo

The domain name configuration.

Note We recommend that you use RuleConditionType and RuleConditionValue rather than this parameter to configure forwarding conditions.
stringNo

The domain name.

The domain name must be 3 to 128 characters in length and can contain letters, digits, hyphens (-), and periods (.). Supported wildcard characters are asterisks (*) and question marks (?).

example.com
RuleActionsobject []Yes

The configurations of the forwarding actions.

OrderintegerYes

The forwarding priority.

Note This parameter does not take effect. Ignore this parameter.
20
RuleActionTypestringYes

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.
  • RemoveHeader: deletes the header of a request.
ForwardGroup
RuleActionValuestringNo

The value of the forwarding action.

You must specify different JSON strings based on the value of RuleActionType.

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 you set RuleActionType 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 you set RuleActionType to Redirect, this parameter specifies the redirect configuration. 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 you set RuleActionType 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 you set RuleActionType 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 you set RuleActionType 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 you set RuleActionType 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: [ ] { } < > # | &.
[{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}]
ForwardGroupConfigobjectNo

The forwarding configuration.

Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding actions.
ServerGroupTuplesobject []Yes

The configuration of an endpoint group.

Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding actions.
EndpointGroupIdstringYes

The ID of an endpoint group.

Note We recommend that you use RuleActionType and RuleActionValue rather than this parameter to configure forwarding actions.
epg-bp1ieei9664r5nv****
ForwardingRuleIdstringYes

The forwarding rule ID.

frule-bp1dii16gu9qdvb34****
ForwardingRuleNamestringNo

The forwarding rule name.

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
RuleDirectionstringNo

The direction in which the rule takes effect. You do not need to configure this parameter.

By default, this parameter is set to request, which specifies that the rule takes effect on requests.

request

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

ForwardingRulesobject []

Details about the forwarding rules.

ForwardingRuleIdstring

The forwarding rule ID.

frule-bp1dii16gu9qdvb34****
RequestIdstring

The request ID.

64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400NotExist.ListenerThe listener does not exist.The listener does not exist.
400NotActive.ListenerThe state of the listener is not active.The listener is unstable.
400NotExist.AcceleratorThe accelerated instance does not exist.The GA instance does not exist.
400StateError.AcceleratorThe state of the accelerated instance is invalid.The status of the GA instance is invalid.
400NotExist.BusinessRegionThe business region does not exist.The business region does not exist.
400NotExist.BasicBandwidthPackageYou must specify the basic bandwidth package.You must specify the basic bandwidth package.
400QuotaExceeded.EndPointThe maximum number of endpoints is exceeded.The maximum number of endpoints is exceeded.
400Exist.EndpointGroupThe endpoint group already exists.The endpoint group already exists.
400NoPermission.VpcEndpointYou 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.
400QuotaExceeded.ForwardingRulehe number of forwarding rule exceeds the limit.-
400QuotaExceeded.RuleConditionConfigThe number of path and host exceeds the limit.-
400RepeatPathAndHost.ForwardingRulepath and host %s repeat-
400NotExist.ForwardingRuleforwarding rule %s is not exist-

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

Change history

Change timeSummary of changesOperation
2023-10-18The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400