API 网关
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > API 网关 > 插件使用 > 条件路由

条件路由

最近更新时间：2024-04-19 14:26:31

我的收藏

本页目录：

操作场景

条件路由插件可根据参数取值转发到不同后端。根据请求的参数取值与系统参数取值，按规则将不同的客户端请求转发到不同后端地址，可广泛应用于灰度发布、蓝绿发布、租户路由等场景。

操作步骤

步骤1：创建插件

1. 登录 API 网关控制台。
2. 在左侧导航栏，单击插件 > 系统插件，进入系统插件列表页。
3. 单击列表左上角的新建，插件类型选择条件路由。
在条件路由插件中，您可最多同时创建10条路由策略，每条策略需要输入的内容如下：
参数
是否必填
说明
策略名称
必填
本条策略的名称，最多50个字符，要求同一插件下不同策略间名称不能一样。
权重
必填
策略匹配的优先级，可输入0-100之间的正整数，不填默认是0。
权重越大匹配优先级越高，权重相同时按创建时间由新到旧的顺序来排优先级。
触发条件
必填
用于判断客户端请求是否符合条件，请输入条件表达式，详见本文条件表达式相关说明。
后端类型
必填
支持公网 URL/IP、内网CLB、后端通道、云函数SCF、Mock、微服务平台 TSF。
后端配置
必填
当客户端请求满足条件时将被转发到的后端，请输入 YAML 格式的后端配置。




步骤2：绑定 API 并生效

1. 在系统插件列表中选中刚刚创建好的插件，单击操作列的绑定 API。
2. 在绑定 API 弹窗中选择服务和环境，并选择需要绑定插件的 API。



3. 单击确定，即可将插件绑定到 API，此时插件的配置已经对 API 生效。

条件表达式写作指南

参数说明

条件表达式支持以下两种类型参数：
请求参数，目前支持 Header、Path、Query 参数。
您在 API 的前端配置中选择了 Header 位置、添加了参数名为 a 的参数，此时在插件中可以用 header.a 指代该参数。
Path 参数无参数名，因此使用 path 指代。例如：path='/test'，即请求路径为 /test 时满足条件。
Path 参数的参数值定义需以'/'开头，如'/test'。
系统参数，目前可使用 sysparam 参数形式来引用当前请求的系统参数，系统参数不需要在 API 中被定义，可以直接引用。但如果您在 API 中定义了重名的参数，则取值会以您自定义的参数为准。系统参数推荐小驼峰写法，大小写不敏感。可用于条件路由插件的系统参数如下：
sysparam.clientIp：客户端 IP。
sysparam.httpScheme：请求的协议 HTTP、HTTPS。
sysparam.clientUa：客户端上传的 UserAgent 字段。
条件表达式支持以下常量类型：
常量类型
说明
示例
STRING
字符串类型
支持单引号或双引号，如："Hello"、'hello'
INTEGER
整数类型
例如：1001、-1
NUMBER
浮点数类型
例如：0.1、100.0
BOOLEAN
布尔类型
例如：true、false

写作规则

1. 可以使用 and、or 来连接不同的表达式。
2. 可以用小括号 (，) 来指定条件判断的优先级。
3. Random() 作为内置函数，可以产生一个 0-1 的 NUMBER 浮点类型参数，用于随机的判断。
4. 如果表达式中使用了不存在的参数，例如 param.unknown = 1，则表达式的判断会返回 false。
5. 支持通过正则表达式函数 regex() 匹配参数值，例如 regex(query.name,"colou?r")。正则表达式字符串需要使用单引号或双引号。
6. 用 exists() 函数来指代是否存在，例如 exists(header.Accept)。
7. == 和 = 都可以用来判断“等于”关系。
8. 用 not( ) 函数来判断“不等于”关系。例如 not(sysparam.clientIp == "120.110.10.199")。

条件表达式示例

5%的几率为真： Random() < 0.05
自定义 Header 参数中的 UserName 是 Admin 且来源 IP 是47.47.74.77： header.UserName = 'Admin' and sysparam.clientIp = '47.47.74.77'
当前请求的用户 Id（Header参数）是1001,1098,2011中的一个，且使用 HTTPS 协议请求： sysparam.httpScheme = 'https' and (header.id = 1001 or header.id = 1098 or header.id = 2011)

后端配置写作指南

支持填写对接公网 URL/IP、内网 CLB、后端通道、云函数 SCF、Mock、微服务平台 TSF 的后端配置：
后端配置必须是 YAML 格式的内容。
字段与 创建API 接口中后端配置的字段一一对应。
创建条件路由插件页已经列出了各后端的配置代码 Demo，您只需要修改参数值，即可完成配置。

公网 URL/IP

ServiceType: HTTP
ServiceConfig:
  Method: GET		# 后端服务方法
  Path: '/test'			# 后端服务路径
  Url: 'http://test.com'	# 后端服务URL
ReserveReqHost: true	#是否保留请求Host（默认为true）
ServiceTimeout: 15	 # api后端超时时间（默认为15s）

内网CLB

ServiceType: HTTP  
ServiceConfig:
  Method: GET       # 后端服务请求方法
  Path: /test 		# 后端服务路径
  Url: 'http://test.com'		#后端服务URL
  UniqVpcId: vpc-xxxxx		# VPC 唯一ID
  Product: clb		# 标示后端为内网CLB资源（请保留）
ReserveReqHost: true	#是否保留请求Host（默认为true）
ServiceTimeout: 15	 # api后端超时时间（默认为15s）

后端通道

ServiceConfig:
  Method: GET	  # 后端服务请求方法
  Path: '/test'			# 后端服务路径
  Url: ''				#后端服务URL
  UniqVpcId: vpc-xxxxxx		# VPC 唯一ID
  UpstreamId: 'upstream-xxxxxx'	# 后端通道唯一ID
  Product: upstream		# 标示后端为后端通道（请保留）
ReserveReqHost: true	#是否保留请求Host（默认为true）
ServiceType: HTTP
ServiceTimeout: 15	 # api后端超时时间（默认为15s）

后端对接云函数 SCF

ServiceType: SCF
ServiceScfFunctionName: scftest		# SCF 函数名称
ServiceScfFunctionNamespace: mynamespace	# SCF 函数命名空间
ServiceScfFunctionQualifier: $LATEST       #示例表示以新发布版本号为准，也可填写具体版本号，如版本为3则需要写为'3'
ServiceScfFunctionType: EVENT		# SCF 函数类型，事件函数（EVENT）web函数（HTTP）
ServiceScfIsIntegratedResponse: false	# 是否开启响应集成
ServiceTimeout: 15	 # api后端超时时间（默认为15s）


后端对接 Mock

ServiceType: MOCK  
ServiceMockReturnMessage: hello mock from strategy  # 后端 Mock 返回信息

后端对接微服务平台 TSF

ServiceType: TSF
X-MicroService-Name: consumer-demo		# 微服务名称
X-NameSpace-Code: mytsf		# 微服务命名空间Code
MicroServices:
  - ClusterId: cls-xxxxxx			# 微服务集群ID
    MicroServiceName: consumer-demo			# 微服务名称
    NamespaceId: namespace-xxxxxx		# 微服务命名空间ID
ServiceConfig:
  Method: ANY	# 后端服务方法
  Path: '/'		# 后端服务路径
  Url: ''	# 后端服务URL
ServiceTsfHealthCheckConf:
  IsHealthCheck: true			# 是否开启健康检查
ServiceTsfLoadBalanceConf:
  IsLoadBalance: true		# 是否开启负载均衡
  Method: RoundRobinRule		# 负载均衡方式
  SessionStickRequired: false		# 是否开启会话保持
ServiceTimeout: 15	 # api后端超时时间（默认为15s）

pluginData

[
    {
        "strategy_name":"route-to-http", // 策略名，最多50个字符，只能包含 A-Za-z0-9 / % ~ _ \\-.{}?&= ，同一插件下策略名不允许重复
        "strategy_weight":2, // 策略匹配的优先级，可输入0-100之间的正整数，不填默认是0
        "condition":"query.age<30 and query.need_verify=false or query.level>3", // 条件表达式
        "backend_type":"HTTP", // 路由转发后端类型，可选值：[MOCK, HTTP, SCF, VPC, UPSTREAM, TSF]
        "backend_config":{  // 后端配置
            "ServiceConfig":{
                "Method":"GET",
                "Path":"/v1/bpi/currentprice.json",
                "Url":"https://api.coindesk.com"
            },
            "ServiceType":"HTTP"
        }
    }
]

注意事项

当请求无法匹配到 API 绑定的条件路由插件中配置的路由策略时，该请求将被转发到 API 默认的后端配置上去。
中国站