Creates forwarding rules.
Operation description
HTTP and HTTPS listeners of Global Accelerator (GA) support domain name-based and path-based forwarding rules. After an HTTP or HTTPS listener receives a request, the system matches the request against the forwarding conditions in a forwarding rule and then performs the corresponding forwarding action. For example, if you set Host to www.example.com
as the forwarding condition and Forward to epg-bp1enpdcrqhl78g6r****
as the forwarding action in a forwarding rule, requests to the www.example.com
domain name match this forwarding rule and are forwarded to the epg-bp1enpdcrqhl78g6r****
endpoint group. Before you call this API operation to create a forwarding rule, we recommend that you understand forwarding rules. For more information, see 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 the ID of a forwarding rule, but the forwarding rule is still being created in the system background. You can call the ListForwardingRules operation to query the state of the forwarding rule.
- If the forwarding rule is in the configuring state, it indicates that the rule is being created. In this case, you can only perform query operations.
- If the forwarding rule is in the active state, it indicates that the rule is created.
-
The CreateForwardingRules operation cannot be repeatedly called for the same GA instance within a specific period of time.
Debugging
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 |
|
| 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 value, but you must make sure that it is unique among different requests. ClientToken can contain only ASCII characters. Note
If you do not set this parameter, ClientToken is set to the value of RequestId. The value of RequestId may be different for each API 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 | Details about the forwarding rules. | test |
object | Yes | Details about the forwarding rules. | ||
Priority | integer | No | The priority of the forwarding rule. Valid values: 1 to 10000. A lower value indicates a higher priority. | 1000 |
RuleConditions | array<object> | Yes | The forwarding conditions. | |
object | No | The forwarding conditions. | ||
RuleConditionType | string | No | The type of the forwarding conditions. Valid values:
| Host |
RuleConditionValue | string | No | The value of the forwarding condition type. You must specify different JSON strings based on the RuleConditionType parameter.
| ["www.example.com", "www.aliyun.com"] |
PathConfig | object | No | The configuration of the path. Note
We recommend that you do not use this parameter. We recommend that you use the RuleConditionType and RuleConditionValue parameters 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 only letters, digits, and the following special characters: $ - _ . + / & ~ @ : '. Supported wildcard characters are asterisks (*) and question marks (?). Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you use RuleConditionType and RuleConditionValue to query 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 only letters, digits, and the following special characters: $ - _ . + / & ~ @ : '. Supported wildcard characters are asterisks (*) and question marks (?). Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you use RuleConditionType and RuleConditionValue to query forwarding conditions.
| /test | |
HostConfig | object | No | The configuration of the domain name. Note
We recommend that you do not use this parameter. We recommend that you use the RuleConditionType and RuleConditionValue parameters to configure forwarding conditions.
| |
Values | array | No | 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 (?). Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you use RuleConditionType and RuleConditionValue to query 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 (.). Supported wildcard characters are asterisks (*) and question marks (?). Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you use RuleConditionType and RuleConditionValue to query forwarding conditions.
| example.com | |
RuleActions | array<object> | Yes | The forwarding action. | |
object | No | 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 |
RuleActionValue | string | No | The value of the forwarding action type. 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.
| [{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}] |
ForwardGroupConfig | object | No | The forwarding configurations. Note
We recommend that you do not use this parameter. We recommend that you use the RuleActionType and RuleActionValue parameters to configure forwarding actions.
| |
ServerGroupTuples | array<object> | Yes | The information about the endpoint group. Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you call RuleActionType and RuleActionValue to query forwarding actions.
| |
object | Yes | The information about the endpoint group. Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you call RuleActionType and RuleActionValue to query forwarding actions.
| ||
EndpointGroupId | string | Yes | The ID of the endpoint group. Note
For GA instances created after July 12, 2022, all forwarding condition types and forwarding action types are supported. We recommend that you call RuleActionType and RuleActionValue to query forwarding actions.
| 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 set this parameter. By default, this parameter is set to request, which indicates that the rule takes effect on requests. | request |
Response parameters
Examples
Sample success responses
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 | 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 |