调用UpdateForwardingRules接口修改转发策略。

使用说明

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

调试

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

请求参数

名称 类型 是否必选 示例值 描述
Action String UpdateForwardingRules

系统规定参数。取值:UpdateForwardingRules

RegionId String cn-hangzhou

全球加速实例所属的地域ID,仅取值:cn-hangzhou

ClientToken String 02fb3da4****

客户端Token,用于保证请求的幂等性。

从您的客户端生成一个参数值,确保不同请求间该参数值唯一。ClientToken只支持ASCII字符。

说明 若您未指定,则系统自动使用API请求的RequestId作为ClientToken标识。每次API请求的RequestId可能不一样。
AcceleratorId String ga-bp17frjjh0udz4q****

全球加速实例ID。

ListenerId String lsr-bp1s0vzbi5bxlx5****

监听ID。

ForwardingRules.N.Priority Integer 1000

转发策略优先级。取值范围:1~10000。值越小表示优先级越高。

ForwardingRules.N.RuleConditions.N.RuleConditionType String Host

转发条件类型。取值:

  • Host:域名。
  • Path:路径。
  • RequestHeader:HTTP标头。
  • Query:查询字符串。
  • Method:HTTP请求方法。
  • Cookie:Cookie。
  • SourceIP:源IP。
ForwardingRules.N.RuleConditions.N.RuleConditionValue String ["www.example.com", "www.aliyun.com"]

转发条件类型对应的值。

根据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时,该参数为请求方法配置信息。取值范围为HEADGETPOSTOPTIONSPUTPATCHDELETE。取值样例为["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"]
ForwardingRules.N.RuleConditions.N.PathConfig Map

路径配置信息。

说明 不推荐使用该参数,建议直接使用RuleConditionTypeRuleConditionValue配置转发条件。
ForwardingRules.N.RuleConditions.N.HostConfig Map

域名配置信息。

说明 不推荐使用该参数,建议直接使用RuleConditionTypeRuleConditionValue配置转发条件。
ForwardingRules.N.RuleActions.N.Order Integer 20

转发优先级。

说明 当前无实际意义,无需配置。
ForwardingRules.N.RuleActions.N.RuleActionType String ForwardGroup

转发动作类型。取值:

  • ForwardGroup:转发。
  • Redirect:重定向。
  • FixResponse:返回固定响应。
  • Rewrite:重写。
  • AddHeader:写入头字段。
  • RemoveHeader:删除头字段。
ForwardingRules.N.RuleActions.N.RuleActionValue String [{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}]

转发动作类型对应的值。

根据RuleActionType传入不同的JSON字符串值。

一个转发规则最多只能有一条ForwardGroupRedirectFixResponse类型的转发动作。RewriteAddHeaderRemoveHeader类型的转发动作顺序必须在ForwardGroup类型的转发动作之前。

  • RuleActionType取值为ForwardGroup时,该参数为虚拟终端节点组信息。仅支持转发至一个虚拟终端节点组。取值样例为{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"},其中:
    • type:取值为endpointgroup
    • value:目标虚拟终端节点组ID。
  • RuleActionType取值为Redirect时,该参数为重定向配置信息。Redirect类型的转发动作中protocoldomainportpathquery不能全部为空或者默认值。取值样例为{"protocol":"HTTP", "domain":"www.example.com", "port":"80", "path":"/a","query":"value1", "code":"301" },其中:
    • protocol:要跳转的协议。取值范围为${protocol}(默认值)、HTTPHTTPS
    • domain:要跳转的域名。默认值为${host}(默认值),您还可以输入其他域名信息,域名长度为3~128个字符,只允许包含小写字母、数字和特殊字符.-?=~_-+/^*!$&|()[]
    • port:要跳转的端口。默认值为${port},您还可以输入端口号,端口取值范围为1~63335。
    • path:要跳转的路径。默认值为${path},路径长度限制为1~128个字符。正则表达式类型的路径,必须以波浪线(~)开头,支持的大小写字母、数字和特殊字符.-_/=?~^*$:()[]+|;非正则表达式类型的路径,必须以正斜线(/) 开头,支持大小写字母、数字和特殊字符.-_/=?:
    • query:要跳转的查询字符串。默认值为${query},您还可以输入其他查询字符串信息,查询字符串长度为1~128个字符,支持ASCII码值ch >= 32 && ch < 127范围内可打印字符,如果是字母必须为小写字母,不支持空格和特殊字符[]{}<>#|&
    • code:跳转方式。支持301302303307308
  • RuleActionType取值为FixResponse时,该参数为返回固定响应配置信息。取值样例为{"code":"200", "type":"text/plain", "content":"dssacav" },其中:
    • code:响应状态码。仅支持2xx4xx5xx数字型字符串,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标头字段内容,内容不能为空。typeuser-defined(用户指定)时,长度为1~128个字符,支持ASCII码值ch >= 32 && ch < 127范围内的可打印字符,支持大小写字母、数字、短划线(-)和下划线(_),开头和结尾不能为空格;typeref(引用)时,长度为1~128个字符,支持大小写字母、数字、短划线(-)和下划线(_),开头和结尾不能为空格;typesystem-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范围内可打印字符,如果是字母必须为小写字母,不支持空格和特殊字符[]{}<>#|&
ForwardingRules.N.RuleActions.N.ForwardGroupConfig Map

转发配置。

说明 不推荐使用该参数,建议直接使用RuleActionTypeRuleActionValue配置转发动作。
ForwardingRules.N.ForwardingRuleId String frule-bp1dii16gu9qdvb34****

转发策略ID。

ForwardingRules.N.ForwardingRuleName String test

转发策略名称。

名称长度为2~128个英文或中文字符,必须以大小写字母或中文开头,可包含数字、半角句号(.)、下划线(_)和短划线(-)。

ForwardingRules.N.RuleDirection String request

规则生效方向。无需配置。

目前默认为request,表示请求方向生效。

返回数据

名称 类型 示例值 描述
ForwardingRules Array of ForwardingRules

转发策略信息。

ForwardingRuleId String frule-bp1dii16gu9qdvb34****

转发策略ID。

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

请求ID。

示例

请求示例

http(s)://[Endpoint]/?Action=UpdateForwardingRules
&RegionId=cn-hangzhou
&ClientToken=02fb3da4****
&AcceleratorId=ga-bp17frjjh0udz4q****
&ListenerId=lsr-bp1s0vzbi5bxlx5****
&ForwardingRules=[{"Priority":1000,"RuleConditions":[{"RuleConditionType":"Host","RuleConditionValue":"[\"www.example.com\", \"www.aliyun.com\"]"}],"RuleActions":[{"Order":20,"RuleActionType":"ForwardGroup","RuleActionValue":"[{\"type\":\"endpointgroup\", \"value\":\"epg-bp1enpdcrqhl78g6r****\"}]"}],"ForwardingRuleId":"frule-bp1dii16gu9qdvb34****","ForwardingRuleName":"test","RuleDirection":"request"}]
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<UpdateForwardingRulesResponse>
    <ForwardingRules>
        <ForwardingRuleId>frule-bp1dii16gu9qdvb34****</ForwardingRuleId>
    </ForwardingRules>
    <RequestId>64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF</RequestId>
</UpdateForwardingRulesResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

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

错误码

HttpCode 错误码 错误信息 描述
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 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。

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