API 网关条件路由-插件使用-文档中心-腾讯云

操作场景
条件路由插件可根据参数取值转发到不同后端。根据请求的参数取值与系统参数取值，按规则将不同的客户端请求转发到不同后端地址，可广泛应用于灰度发布、蓝绿发布、租户路由等场景。
操作步骤
步骤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 默认的后端配置上去。

参数	是否必填	说明
策略名称	必填	本条策略的名称，最多50个字符，要求同一插件下不同策略间名称不能一样。
权重	必填	策略匹配的优先级，可输入0-100之间的正整数，不填默认是0。权重越大匹配优先级越高，权重相同时按创建时间由新到旧的顺序来排优先级。
触发条件	必填	用于判断客户端请求是否符合条件，请输入条件表达式，详见本文条件表达式相关说明。
后端类型	必填	支持公网 URL/IP、内网CLB、后端通道、云函数SCF、Mock、微服务平台 TSF。
后端配置	必填	当客户端请求满足条件时将被转发到的后端，请输入 YAML 格式的后端配置。

常量类型	说明	示例
STRING	字符串类型	支持单引号或双引号，如："Hello"、'hello'
INTEGER	整数类型	例如：1001、-1
NUMBER	浮点数类型	例如：0.1、100.0
BOOLEAN	布尔类型	例如：true、false

条件路由

本页目录：

操作场景

操作步骤

步骤1：创建插件

步骤2：绑定 API 并生效

条件表达式写作指南

参数说明

写作规则

条件表达式示例

后端配置写作指南

公网 URL/IP

内网CLB

后端通道

后端对接云函数 SCF

后端对接 Mock

后端对接微服务平台 TSF

pluginData

注意事项