调用CreateForwardingRules创建转发规则_全球加速(GA)-阿里云帮助中心

如果您的业务需要根据请求的属性（域名、路径等）或请求中包含的数据信息（HTTP标头、Cookie等）来进行流量分发和处理，您可以自定义监听的转发规则。监听会根据转发规则对访问请求执行不同的转发动作。您可以通过调用CreateForwardingRules接口创建转发规则。

接口说明

在您调用本接口创建转发规则前，建议您先了解转发规则原理及匹配规则。更多信息，请参见转发策略。

调用本接口时，请注意以下事项：

CreateForwardingRules 接口属于异步接口，即系统会先返回一个转发策略 ID，但转发策略并未创建完成，系统后台的创建任务仍在进行。您可以调用 ListForwardingRules 查询转发策略的状态：
- 当转发策略处于 configuring 状态时，表示转发策略正在创建中，在该状态下，您只能执行查询操作，不能执行其他操作。
- 当转发策略处于 active 状态时，表示转发策略创建完成。
CreateForwardingRules 接口不支持在同一个全球加速实例内并发创建转发策略。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作	访问级别	资源类型	条件关键字	关联操作
ga:CreateForwardingRules	create	Listener `acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}` Accelerator `acs:ga:{#regionId}:{#accountId}:ga/{#acceleratorId}`	无	无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	全球加速实例所属的地域 ID，仅取值：cn-hangzhou。	cn-hangzhou
ClientToken	string	否	客户端 Token，用于保证请求的幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符。说明若您未指定，则系统自动使用 API 请求的 RequestId 作为 ClientToken 标识。每次 API 请求的 RequestId 不一样。	02fb3da4****
AcceleratorId	string	是	全球加速实例 ID。	ga-bp17frjjh0udz4q****
ListenerId	string	是	监听实例 ID。	lsr-bp1s0vzbi5bxlx5****
ForwardingRules	array<object>	是	转发策略配置信息。
	object	是	转发策略配置信息。
Priority	integer	否	转发策略优先级。取值范围：1~10000。值越小表示优先级越高。	1
RuleConditions	array<object>	是	转发条件列表。
	object	否	转发条件列表。
RuleConditionType	string	否	转发条件类型。取值： Host：域名。 Path：路径。 RequestHeader：HTTP 标头。 Query：查询字符串。 Method：HTTP 请求方法。 Cookie：Cookie。 SourceIP：源 IP。	Host
RuleConditionValue	string	否	转发条件类型对应的值。根据 RuleConditionType 传入不同的 JSON 字符串值。当 RuleConditionType 取值为 Host 时，该参数为域名条件配置信息。一个转发策略内只允许创建一个域名类型转发规则，该转发规则内支持配置多个域名，多个域名间为“或”关系。域名长度为 3~128 个字符，允许包含字母、数字、短划线（-）和半角句号（.），支持使用星号（）和半角问号（?）作为通配符。取值样例为`["www.example.com", "www.aliyun.com"]`。当 RuleConditionType* 取值为 Path 时，该参数为路径条件配置信息。一个转发策略内允许创建多个路径类型转发规则，多个路径类型转发规则间为”或“关系，一个转发路径类型规则内支持配置多个路径，多个路径间为“或”关系。路径长度为 1~128 个字符，必须以正斜线（/）开头，只允许包含字母、数字、美元符号（$）、短划线（-）、下划线（_）、半角句号（.）、加号（+）、正斜线（/）、and（&）、波浪线（~）、at（@）、半角冒号（:）、撇号（'），支持使用星号（）和半角问号（?）作为通配符。取值样例为`["/a", "/b/"]`。当 RuleConditionType* 取值为 RequestHeader 时，该参数为 HTTP 标头字段条件配置信息，由键（Key）和值（Value）组成。同一个转发规则条件内标头字段值不能重复。取值样例为`[{"header1":["value1","value2"]}]`。 Key：HTTP 标头的键值长度为 1~40 个字符，支持字母、数字、短划线（-）和下划线（_）。 Value：HTTP 标头的值长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，开头和结尾不能为空格。当 RuleConditionType 取值为 Query 时，该参数为查询字符串条件配置信息，由键（Key）和值（Value）组成。取值样例为`[{"query1":["value1"]}, {"query2":["value2"]}]`。 Key：HTTP 标头的键值长度为 1~100 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和`[]{}<>\;/?:@&=+,$%"^~`。 Value：HTTP 标头的值长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和`[]{}<>\;/?:@&=+,$%"^~`。当 RuleConditionType 取值为 Method 时，该参数为请求方法配置信息。取值范围为 HEAD、GET、POST、OPTIONS、PUT、PATCH、DELETE。取值样例为`["GET", "OPTIONS", "POST"]`。当 RuleConditionType 取值为 Cookie 时，该参数为 Cookie 配置信息，由键（Key）和值（Value）组成。取值样例为`[{"cookie1":["value1"]}, {"cookie2":["value2"]}]` Key：Cookie 的键值长度为 1~100 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和`#[]{}\<>&`。 Value：Cookie 的值长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和`#[]{}\<>&`。当 RuleConditionType 取值为 SourceIP 时，该参数为源 IP 配置信息，支持 IP 地址，例如 1.1.XX.XX/32，或 IP 地址段，例如 2.2.XX.XX/24。一个转发规则只允许创建一个源 IP 规则，该转发规则内支持配置多个源 IP，多个 IP 之间为“或”关系。取值样例为`["1.1.XX.XX/32", "2.2.XX.XX/24"]`。	["www.example.com", "www.aliyun.com"]
PathConfig	object	否	路径配置信息。说明不推荐使用该参数，建议直接使用 RuleConditionType 和 RuleConditionValue 配置转发条件。
Values	array	否	路径配置。路径长度为 1~128 个字符，必须以正斜线（/）开头，只允许包含字母、数字、美元符号（$）、短划线（-）、下划线（_）、半角句号（.）、加号（+）、正斜线（/）、and（&）、波浪线（~）、at（@）、半角冒号（:）、半角单引号（'），支持使用星号（）和半角问号（?）作为通配符。说明不推荐使用该参数，建议直接使用 RuleConditionType* 和 RuleConditionValue 配置转发条件。
	string	否	路径配置。路径长度为 1~128 个字符，必须以正斜线（/）开头，只允许包含字母、数字、美元符号（$）、短划线（-）、下划线（_）、半角句号（.）、加号（+）、正斜线（/）、and（&）、波浪线（~）、at（@）、半角冒号（:）、半角单引号（'），支持使用星号（）和半角问号（?）作为通配符。说明不推荐使用该参数，建议直接使用 RuleConditionType* 和 RuleConditionValue 配置转发条件。	/test
HostConfig	object	否	域名配置信息。说明不推荐使用该参数，建议直接使用 RuleConditionType 和 RuleConditionValue 配置转发条件。
Values	array	否	域名配置。说明不推荐使用该参数，建议直接使用 RuleConditionType 和 RuleConditionValue 配置转发条件。
	string	否	域名。域名长度为 3~128 个字符，允许包含字母、数字、短划线（-）和半角句号（.），支持使用星号（）和半角问号（?）作为通配符。说明不推荐使用该参数，建议直接使用 RuleConditionType* 和 RuleConditionValue 配置转发条件。	example.com
RuleActions	array<object>	是	转发动作。
	object	否	转发动作。
Order	integer	是	转发优先级。说明当前无实际意义，无需配置。	20
RuleActionType	string	是	转发动作类型。取值： ForwardGroup：转发。 Redirect：重定向。 FixResponse：返回固定响应。 Rewrite：重写。 AddHeader：写入头字段。 RemoveHeader：删除头字段。 Drop：丢弃。	ForwardGroup
RuleActionValue	string	否	转发动作类型对应的值。根据 RuleActionType 传入不同的 JSON 字符串值。一个转发规则最多只能有一条 ForwardGroup、Redirect、FixResponse 类型的转发动作。Rewrite、AddHeader、RemoveHeader 类型的转发动作顺序必须在 ForwardGroup 类型的转发动作之前。当 RuleActionType 取值为 ForwardGroup 时，该参数为虚拟终端节点组信息。仅支持转发至一个虚拟终端节点组。取值样例为`{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r**"}`，其中： `type`：取值为`endpointgroup`。 `value`：目标虚拟终端节点组 ID。当 RuleActionType 取值为 Redirect 时，该参数为重定向配置信息。Redirect** 类型的转发动作中`protocol`、`domain`、`port`、`path`、`query`不能全部为空或者默认值。取值样例为`{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" }`，其中： `protocol`：要跳转的协议。取值范围为`${protocol}`（默认值）、`HTTP`、`HTTPS`。 `domain`：要跳转的域名。默认值为`${host}`（默认值），您还可以输入其他域名信息，域名长度为 3~128 个字符，只允许包含小写字母、数字和特殊字符`.-?=~_-+/^!$&()[]`。 `port`：要跳转的端口。默认值为`${port}`，您还可以输入端口号，端口取值范围为 1~63335。 `path`：要跳转的路径。默认值为`${path}`，路径长度限制为 1~128 个字符。正则表达式类型的路径，必须以波浪线（~）开头，支持的大小写字母、数字和特殊字符`.-_/=?~^$:()[]+`；非正则表达式类型的路径，必须以正斜线（/）开头，支持大小写字母、数字和特殊字符`.-_/=?:`。 `query`：要跳转的查询字符串。默认值为`${query}`，您还可以输入其他查询字符串信息，查询字符串长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和特殊字符`[]{}<>\#&`。 `code`：跳转方式。支持`301`、`302`、`303`、`307`或`308`。当 RuleActionType 取值为 FixResponse 时，该参数为返回固定响应配置信息。取值样例为`{"code":"200", "type":"text/plain", "content":"dssacav" }`，其中： `code`：响应状态码。仅支持`2xx`、`4xx`、`5xx`数字型字符串，`x`为任意数字。 `type`：响应正文类型。仅支持text/plain, text/css, text/html, application/javascript, application/json。 `content`：响应正文。响应正文长度不能超过 1000 个字符，不支持中文字符。当 RuleActionType 取值为 AddHeader 时，该参数为插入 HTTP 标头字段配置信息。转发规则中存在 AddHeader 类型的转发动作，必须同时配置一条 ForwardGroup 类型的转发动作。取值样例为`[{"name":"header1","type":"userdefined", "value":"value"}]`，其中： `name`：HTTP 标头字段名称。名称长度为 1~40 字符，支持大小写字母、数字、短划线（-）和下划线（_）。AddHeader 中的 HTTP 标头字段名称不能重复，也不能和 RemoveHeader 中的 HTTP 标头字段名称重复。 `type`：HTTP 标头字段内容类型。取值范围为`user-defined`（用户指定）、`ref`（引用）、`system-defined`（系统定义）。 `value`：HTTP 标头字段内容，内容不能为空。`type`为`user-defined`（用户指定）时，长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内的可打印字符，支持大小写字母、数字、短划线（-）和下划线（），开头和结尾不能为空格；`type`为`ref`（引用）时，长度为 1~128 个字符，支持大小写字母、数字、短划线（-）和下划线（），开头和结尾不能为空格；`type`为`system-defined`（系统定义）时，仅支持取值为`ClientSrcIp`。当 RuleActionType 取值为 RemoveHeader 时，该参数为删除 HTTP 标头字段信息。转发规则中存在 RemoveHeader 类型的转发动作，必须同时配置一条 ForwardGroup 类型的转发动作。长度为 1~40 字符，支持大小写字母、数字、短划线（-）和下划线（_）。取值样例为`["header1"]`。当 RuleActionType 取值为 Rewrite 时，该参数为重写配置信息。转发规则中存在 Rewrite 类型的转发动作，必须同时配置一条 ForwardGroup 类型的转发动作。取值样例为`{"domain":"value1", "path":"value2", "query":"value3"}`，其中： `domain`：要跳转的域名。默认值为`${host}`，您还可以输入其他域名信息，域名长度为 3~128 个字符，只允许包含小写字母、数字和特殊字符`.-?=~_-+/^!$&()[]`。 `path`：要跳转的路径。默认值为`${path}`，路径长度限制为 1~128 个字符。正则表达式类型的路径，必须以波浪线（~）开头，支持的大小写字母、数字和特殊字符`.-_/=?~^$:()[]+`；非正则表达式类型的路径，必须以正斜线（/）开头，支持大小写字母、数字和特殊字符`.-_/=?:`。 `query`：要跳转的查询字符串。默认值为`${query}`，您还可以输入其他查询字符串信息，查询字符串长度为 1~128 个字符，支持 ASCII 码值`ch >= 32 && ch < 127`范围内可打印字符，如果是字母必须为小写字母，不支持空格和特殊字符`[]{}<>\#&`。当 RuleActionType 取值为 Drop 时，该参数无需填写。	[{"type":"endpointgroup","value":"epg-bp1l49ltx6iengvf2ks5z****"}]
ForwardGroupConfig	object	否	转发配置。说明不推荐使用该参数，建议直接使用 RuleActionType 和 RuleActionValue 配置转发动作。
ServerGroupTuples	array<object>	是	终端节点组配置。说明不推荐使用该参数，建议直接使用 RuleActionType 和 RuleActionValue 配置转发动作。
	object	是	终端节点组配置。说明不推荐使用该参数，建议直接使用 RuleActionType 和 RuleActionValue 配置转发动作。
EndpointGroupId	string	是	终端节点组 ID。说明不推荐使用该参数，建议直接使用 RuleActionType 和 RuleActionValue 配置转发动作。	epg-bp1nktp3qgbcq9ih6****
ForwardingRuleName	string	否	转发策略名称。长度为 2~128 个英文或中文字符，必须以大小写字母或中文开头，可包含数字、半角句号（.）、下划线（_）和短划线（-）。	test
RuleDirection	string	否	规则生效方向。无需配置。目前默认为 request，表示请求方向生效。	request

返回参数

名称	类型	描述	示例值
	object	返回信息列表。
RequestId	string	请求 ID。	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF
ForwardingRules	array<object>	转发策略信息。
ForwardingRules	object	转发策略信息。
ForwardingRuleId	string	转发策略 ID。	frule-bp1dii16gu9qdvb34****

示例

正常返回示例

JSON格式

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

错误码

HTTP status code	错误码	错误信息	描述
400	NotExist.Listener	The listener does not exist.	监听器不存在
400	NotActive.Listener	The state of the listener is not active.	监听器状态非稳态
400	NotExist.Accelerator	The accelerated instance does not exist.	加速实例不存在。
400	StateError.Accelerator	The state of the accelerated instance is invalid.	加速实例状态非法。
400	NotExist.BusinessRegion	The business region does not exist.	业务region并不存在
400	NotExist.BasicBandwidthPackage	You must specify the basic bandwidth package.	缺少基础带宽包
400	QuotaExceeded.EndPoint	The maximum number of endpoints is exceeded.	终端节点达到Quota限制
400	Exist.EndpointGroup	The endpoint group already exists.	终端节点组已存在
400	NoPermission.VpcEndpoint	You are not authorized to perform the operation.	用户没有创建服务关联角色的权限，请联系主账号或权限管理员授权当前用户AliyunGlobalAccelerationFullAccess或者创建服务关联角色的自定义权限。自定义权限策略的相关信息包含以下内容：ServiceName为vpcendpoint.ga.aliyuncs.com，服务关联角色名称为AliyunServiceRoleForGaVpcEndpoint，执行该操作所需的用户权限为ram:CreateServiceLinkedRole。
400	QuotaExceeded.ForwardingRule	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.	路径和域名重复
400	QuotaExceeded.RuleConditionConfig	The number of paths and hosts exceeds the limit.	路径和域名数量超过限制

访问错误中心查看更多错误码。

变更历史

变更时间	变更内容概要	操作
2024-04-22	OpenAPI 错误码发生变更	查看变更详情
2023-04-20	OpenAPI 错误码发生变更	查看变更详情