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

创建转发策略。

接口说明

全球加速HTTP或HTTPS协议的监听支持配置基于域名和路径等类型的转发策略。HTTP或HTTPS协议的监听接收到访问请求后，访问请求首先会匹配转发策略中的配置的转发条件，再根据转发条件执行对应的转发动作。例如转发策略中配置了基于域名为www.example.com的转发条件及转发至epg-bp1enpdcrqhl78g6r****的转发动作，那么当有访问www.example.com的请求时，将匹配到该转发策略，访问请求将最终被转发至终端节点组epg-bp1enpdcrqhl78g6r****。在您调用本接口创建转发策略前，建议您先了解转发策略的转发规则。更多信息，请参见转发策略。

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

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

调试

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

调试

授权信息

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

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

操作	访问级别	资源类型	条件关键字	关联操作
ga:CreateForwardingRules	Write	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	object []	是	转发策略配置信息列表。	test
Priority	integer	否	转发策略优先级。取值范围：1~10000。值越小表示优先级越高。	1000
RuleConditions	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	否	路径配置信息。说明不推荐使用该参数，建议直接使用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	object []	是	转发动作。
Order	integer	是	转发优先级。说明当前无实际意义，无需配置。	20
RuleActionType	string	是	转发动作类型。取值： ForwardGroup：转发。 Redirect：重定向。 FixResponse：返回固定响应。 Rewrite：重写。 AddHeader：写入头字段。 RemoveHeader：删除头字段。	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`范围内可打印字符，如果是字母必须为小写字母，不支持空格和特殊字符`[]{}<>\#\|&`。	[{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}]
ForwardGroupConfig	object	否	转发配置。说明不推荐使用该参数，建议直接使用RuleActionType和RuleActionValue配置转发动作。
ServerGroupTuples	object []	是	终端节点组配置。说明不推荐使用该参数，建议直接使用RuleActionType和RuleActionValue配置转发动作。
EndpointGroupId	string	是	终端节点组ID。说明不推荐使用该参数，建议直接使用RuleActionType和RuleActionValue配置转发动作。	epg-bp1ieei9664r5nv****
ForwardingRuleName	string	否	转发策略名称。名称长度为2~128个英文或中文字符，必须以大小写字母或中文开头，可包含数字、半角句号（.）、下划线（_）和短划线（-）。	test
RuleDirection	string	否	规则生效方向。无需配置。目前默认为request，表示请求方向生效。	request

返回参数

名称	类型	描述	示例值
	object	返回信息列表。
RequestId	string	请求ID。	64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF
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	QuotaExceeded.RuleConditionConfig	The number of path and host exceeds the limit.	-
400	RepeatPathAndHost.ForwardingRule	path and host %s repeat	-

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

变更历史

变更时间

变更内容概要

操作

2023-04-20

OpenAPI 错误码发生变更

看变更集

变更项	变更内容
错误码	OpenAPI 错误码发生变更
	删除错误码：400