文档

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:CreateForwardingRulesWrite
  • Listener
    acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}
  • Accelerator
    acs:ga:{#regionId}:{#accountId}:ga/{#acceleratorId}

请求参数

名称类型必填描述示例值
RegionIdstring

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

cn-hangzhou
ClientTokenstring

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

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

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

全球加速实例 ID。

ga-bp17frjjh0udz4q****
ListenerIdstring

监听实例 ID。

lsr-bp1s0vzbi5bxlx5****
ForwardingRulesobject []

转发策略配置信息列表。

test
Priorityinteger

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

1000
RuleConditionsobject []

转发条件列表。

RuleConditionTypestring

转发条件类型。取值:

  • Host:域名。
  • Path:路径。
  • RequestHeader:HTTP 标头。
  • Query:查询字符串。
  • Method:HTTP 请求方法。
  • Cookie:Cookie。
  • SourceIP:源 IP。
Host
RuleConditionValuestring

转发条件类型对应的值。 根据 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"]

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

路径配置信息。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
Valuesarray

路径配置信息。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
string

路径。

路径长度为 1~128 个字符,必须以正斜线(/)开头,只允许包含字母、数字、美元符号($)、短划线(-)、下划线(_)、半角句号(.)、加号(+)、正斜线(/)、and(&)、波浪线(~)、at(@)、半角冒号(:)、半角单引号('),支持使用星号(*)和半角问号(?)作为通配符。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
/test
HostConfigobject

域名配置信息。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
Valuesarray

域名配置信息。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
string

域名。

域名长度为 3~128 个字符,允许包含字母、数字、短划线(-)和半角句号(.),支持使用星号(*)和半角问号(?)作为通配符。

说明 不推荐使用该参数,建议直接使用 RuleConditionTypeRuleConditionValue 配置转发条件。
example.com
RuleActionsobject []

转发动作。

Orderinteger

转发优先级。

说明 当前无实际意义,无需配置。
20
RuleActionTypestring

转发动作类型。取值:

  • ForwardGroup:转发。
  • Redirect:重定向。
  • FixResponse:返回固定响应。
  • Rewrite:重写。
  • AddHeader:写入头字段。
  • RemoveHeader:删除头字段。
ForwardGroup
RuleActionValuestring

转发动作类型对应的值。

根据 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范围内可打印字符,如果是字母必须为小写字母,不支持空格和特殊字符[]{}<>\#|&

[{"type":"endpointgroup", "value":"epg-bp1enpdcrqhl78g6r****"}]
ForwardGroupConfigobject

转发配置。

说明 不推荐使用该参数,建议直接使用 RuleActionTypeRuleActionValue 配置转发动作。
ServerGroupTuplesobject []

终端节点组配置。

说明 不推荐使用该参数,建议直接使用 RuleActionTypeRuleActionValue 配置转发动作。
EndpointGroupIdstring

终端节点组 ID。

说明 不推荐使用该参数,建议直接使用 RuleActionTypeRuleActionValue 配置转发动作。
epg-bp1ieei9664r5nv****
ForwardingRuleNamestring

转发策略名称。

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

test
RuleDirectionstring

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

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

request

返回参数

名称类型描述示例值
object

返回信息列表。

RequestIdstring

请求 ID。

64ADAB1E-0B7F-4FD8-A404-3BECC0E9CCFF
ForwardingRulesobject []

转发策略信息。

ForwardingRuleIdstring

转发策略 ID。

frule-bp1dii16gu9qdvb34****

示例

正常返回示例

JSON格式

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

错误码

HTTP status code错误码错误信息描述
400NotExist.ListenerThe listener does not exist.监听器不存在
400NotActive.ListenerThe state of the listener is not active.监听器状态非稳态
400NotExist.AcceleratorThe accelerated instance does not exist.加速实例不存在。
400StateError.AcceleratorThe state of the accelerated instance is invalid.加速实例状态非法。
400NotExist.BusinessRegionThe business region does not exist.业务region并不存在
400NotExist.BasicBandwidthPackageYou must specify the basic bandwidth package.缺少基础带宽包
400QuotaExceeded.EndPointThe maximum number of endpoints is exceeded.终端节点达到Quota限制
400Exist.EndpointGroupThe endpoint group already exists.终端节点组已存在
400NoPermission.VpcEndpointYou are not authorized to perform the operation.用户没有创建服务关联角色的权限,请联系主账号或权限管理员授权当前用户AliyunGlobalAccelerationFullAccess或者创建服务关联角色的自定义权限。自定义权限策略的相关信息包含以下内容:ServiceName为vpcendpoint.ga.aliyuncs.com,服务关联角色名称为AliyunServiceRoleForGaVpcEndpoint,执行该操作所需的用户权限为ram:CreateServiceLinkedRole。
400QuotaExceeded.ForwardingRuleThe number of forwarding rule exceeds the limit.转发规则数量超过限制
400QuotaExceeded.RuleConditionConfigThe number of path and host exceeds the limit.-
400RepeatPathAndHost.ForwardingRulepath and host %s repeat-

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

变更历史

变更时间变更内容概要操作
2023-04-20OpenAPI 错误码发生变更看变更集
变更项变更内容
错误码OpenAPI 错误码发生变更
    删除错误码:400
  • 本页导读 (1)
文档反馈