AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 API 网关 云原生API网关 操作指南 API管理 REST API 配置策略与插件

配置策略与插件

更新时间：
产品详情
我的收藏

云原生API网关支持对API和接口级进行添加策略和配置插件，提高API和接口的安全性、性能和可维护性。

重要

  • 策略配置修改后即时生效，无需重新发布。

  • API级策略的插件配置默认应用于接口级。

  • 接口不允许删除API级策略，支持接口级的策略覆盖API级策略。

操作步骤

  1. 云原生API网关提供了实例内和实例外两种添加API策略的方式：

    实例外API

    1. 登录云原生API网关控制台。左侧导航栏选择API，并在顶部菜单栏选择地域。

    2. 单击目标API，您可以在下拉框中选择需要添加策略的实例。image

    实例内API

    1. 登录云原生API网关控制台。左侧导航栏选择实例，并在顶部菜单栏选择地域。

    2. 在实例页面，单击目标网关实例ID。左侧导航栏选择API，单击目标API。

  2. 您可以进行API级或接口级策略&插件配置：

    • API级：单击API策略配置页签，针对全部接口进行API级策略&插件配置，然后单击启用策略/插件。

    • 接口级：在接口列表页签单击目标接口，单击策略配置页签，然后单击启用策略/插件。

  3. 在启用策略/插件面板中，选择策略或插件进行配置。详情请参见策略配置和插件配置。

策略配置

限流策略

云原生API网关支持在API和接口级别上实施限流策略，有效防止外部请求超过后端服务的承载能力并避免级联雪崩的发生。在高并发场景下，限流通过阻止部分请求来确保后端服务始终可用。使您能够精准控制每个API和接口在指定时间周期内的请求数量，不超过预设的阈值。

限流策略包含并发控制、流量控制和熔断策略。

  • 并发控制策略：并发规则的原理是统计当前网关处理中的请求数之和，当指标达到设定的阈值时立即拦截流量，可配置为后端服务的最大并发处理请求数，实现在高并发下的后端服务可用性保护。

    操作步骤

    您可在添加策略页面，单击并发控制卡片，在添加策略: 并发控制面板配置相关参数。

    配置项

    说明

    是否开启

    开启后，并发规则生效。

    总体并发数阈值

    设置总体并发数阈值。

    Web fallback 行为

    返回指定内容

    HTTP状态码

    设置HTTP状态码。默认为429。

    返回 content-type

    选择返回 content-type为普通文本或JSON。

    HTTP 返回文本

    输入返回文本。

    返回指定内容

    跳转地址

    输入跳转地址。

  • 流量控制策略：流控规则的原理是监控API和接口的QPS指标，当指标达到设定的阈值时立即拦截流量，避免后端服务被瞬时的流量高峰冲垮，从而保障高可用性。

    操作步骤

    您可在添加策略页面，单击流量控制卡片，在添加策略: 流量控制面板配置相关参数。

    配置项

    说明

    是否开启

    开启后，流量控制规则生效。

    总体QPS阈值

    设置总体QPS阈值。

    Web fallback 行为

    返回指定内容

    HTTP状态码

    设置HTTP状态码。默认为429。

    返回 content-type

    选择返回 content-type为普通文本或JSON。

    HTTP 返回文本

    输入返回文本。

    跳转到指定页面

    跳转地址

    输入跳转地址。

  • 熔断策略：熔断规则的原理是监控API和接口的响应时间或异常比例，当达到指定的阈值时立即降低依赖优先级。在指定的时间内，系统不会调用该不稳定的资源，避免后端服务受到影响，从而保障后端的高可用性。当指定时间过后，再重新恢复对该资源的调用。

    操作步骤

    您可在添加策略页面，单击熔断卡片，在添加策略: 熔断面板配置相关参数。

    配置项

    说明

    是否开启

    开启后，熔断规则生效。

    统计窗口时长

    统计的时间窗口长度，取值范围为1秒~120分钟。

    最小请求数目

    触发熔断的最小请求数目，若当前统计窗口内的请求数小于此值，即使达到熔断条件规则也不会触发。

    阈值类型

    选择以慢调用比例（%）或异常比例（%）作为阈值。

    1. 选择以慢调用比例（%）作为阈值，需要设置允许的慢调用RT（即最大的响应时间），请求的响应时间大于该值则统计为慢调用。在降级阈值中设置触发熔断的慢调用比例。规则开启后，在单位统计时长内请求数目大于设置的最小请求数目，并且慢调用的比例大于阈值，则接下来的熔断时长内请求会自动被熔断。经过熔断时长后，熔断器会进入探测恢复状态，若接下来的一个请求响应时间小于设置的慢调用RT，则结束熔断；若大于设置的慢调用RT，则会再次被熔断。

    2. 选择以异常比例（%）作为阈值，需要在降级阈值中设置触发熔断的异常比例。规则开启后，在单位统计时长内业务异常数目大于设置的最小请求数目，并且异常的比例大于阈值，则接下来的熔断时长内请求会自动被熔断。

    慢调用RT

    设置允许的慢调用RT（即最大的响应时间）。

    熔断比例阈值

    触发熔断的慢调用比例阈值，取值范围 0-100（代表 0%-100%）。

    熔断时长（s）

    即熔断触发后持续的时间。资源进入熔断状态后，在配置的熔断时长内，请求都会快速失败。

    Web fallback 行为

    返回指定内容

    HTTP状态码

    设置HTTP状态码。默认为429。

    返回 content-type

    选择返回 content-type为普通文本或JSON。

    HTTP 返回文本

    输入返回文本。

    跳转到指定页面

    跳转地址

    输入跳转地址。

重写策略

通过配置重写策略，您可以在将请求转发至目标后端服务之前灵活地修改请求路径和主机域，以满足特定业务环境和架构的需求。重写策略能够精确控制请求的路径和主机域，从而确保请求被正确API和接口到合适的服务或端点。

操作步骤

您可在添加策略页面，单击HTTP重写进入添加策略: HTTP重写面板配置相关参数。

  • 路径（Path）重写

    对于路径（Path）重写，云原生API网关支持以下两种重写模式。

    • 精确重写：仅支持接口级重写。

    • 正则重写：支持接口级和API级重写。

    精确重写

    精确重写可以修改原始请求的Path前缀。

    示例一

    原始请求的Path为/app/test，但转发给后端服务的Path为/test，配置方式建议如下：

    • API和接口匹配条件：匹配方式为精确匹配，Path为/app/。

    • 重写：重写方式为精确重写，Path为/。

    说明

    API和接口匹配条件的Path必须设置为/app/，因为精确重写只会修改精确匹配字符串。如果API和接口匹配条件的Path设置为/app，那么经重写后的Path结果将会是//test，不符合预期。

    示例二

    原始请求的Path为/v1/test，但转发给后端服务的Path为/v2/test。配置方式建议如下：

    • API和接口匹配条件：匹配方式为精确匹配，Path为/v1。

    • 重写：重写方式为精确重写，Path为/v2。

    重要

    精确重写要求API和接口的匹配方式为精确匹配，精确匹配和正则匹配不支持精确重写。由于API和接口匹配方式为精确匹配且可以匹配所有带有指定前缀Path的请求，所以您在配置精确重写时需要关注是否需要对所有这些请求进行重写，否则建议使用精确重写。

    正则重写

    正则重写可以部分修改原始请求的Path。正则重写包括两个元素，一个是模式匹配串，用于匹配Path上需要修改的部分；另一个是替换串，用于替换匹配成功的Path部分。关于正则表达式的规范，请参见正则表达式语法。

    示例一

    原始请求的Path为/aaa/one/bbb/one/ccc，但转发给后端服务的Path为/aaa/two/bbb/two/ccc，配置方式建议如下：

    • API和接口匹配条件：匹配方式为精确匹配，Path为/aaa/one/bbb/one/ccc。

    • 重写：重写方式为正则重写，模式串为one，替换串为two。

    示例二

    原始请求的Path为/httpbin/(.*)/(.*)，希望去掉前缀/httpbin并且将两个正则表达式部分进行位置交换，配置方式建议如下：

    • API和接口匹配条件：匹配方式为正则匹配，Path为/httpbin/(.*)/(.*)。

    • 重写：重写方式为正则重写，模式串为/httpbin/(.*)/(.*)，替换串为/\2/\1，其中\1表示第一个正则匹配到的字符串，\2表示第二个正则匹配到的字符串，对应Nginx中的$1，$2用法。

    示例三

    对于开启版本管理并且使用方式为Path的REST API，希望往后端转发时去掉请求path中的版本字段。例如：原始请求Path为/basePath/version/order/get，但转发给后端服务的Path为/basePath/order/get，配置方式建议如下：

    • 选择使用 API策略配置

    • 重写：重写方式为正则重写，模式串为(/.*)/version(/.*)，替换串为\1\2，其中\1表示第一个正则匹配到的字符串，\2表示第二个正则匹配到的字符串，对应Nginx中的$1，$2用法。

    说明

    正则重写属于高阶用法，语法较为复杂且一般用于特殊的场景，建议您选择精确重写。

  • 主机域（Host）重写

    对于主机域（Host）重写，云原生API网关支持精确重写。

    例如，原始请求的Host为test.com，但转发给后端服务的Host为dev.com，在重写策略中将重写主机设置为dev.com。

Header修改策略

在将请求转发至目标后端服务之前，或在后端服务的响应返回给客户端之前，Header设置功能允许您修改原始请求中的头信息。

操作步骤

您可在添加策略页面，单击Header修改卡片，在添加策略: Header修改面板配置相关参数。

配置项

说明

开启

是否开启Header修改策略。

  • 开启：开启Header修改策略后，网关会控制请求和响应的Header。

  • 关闭：关闭Header修改策略后，网关不会控制请求和响应的Header。

Header类型

选择Header类型。

  • 请求：表示将会对请求的Header进行设置。

  • 响应：表示将会对响应的Header进行设置。

操作类型

选择操作类型。

  • 新增：向请求或响应新增一个Header。

    说明

    如果新增的Header已存在，那么Header Value将会拼接在已有的Header值后面，并通过英文逗号（,）分隔。

  • 修改：修改请求或响应指定的Header。

    说明

    • 如果指定的Header不存在，将会按照Header Key和Header Value进行新增操作。

    • 如果指定的Header存在，将会进行覆盖修改操作。

  • 删除：删除请求或响应指定的Header。

Header Key

输入请求或响应的头部名。

Header Value

输入请求或响应的头部值。

跨域资源共享策略

跨域资源共享（CORS，Cross-Origin Resource Sharing）是一项重要的安全策略，允许Web应用服务器进行跨域访问控制，从而实现安全的数据传输。云原生API网关支持在API和接口级别配置跨域策略，您可以根据实际需求，限定允许访问资源的域名和请求方法。

重要

跨域对于Mock服务不生效，请配置一个真实的后端测试服务。

操作步骤

您可在添加策略页面，单击跨域卡片，在添加策略: 跨域面板配置相关参数。

配置项

描述

开启

打开开启右侧的开关。

  • 开启：开启跨域策略后，您的服务器资源允许被设置的第三方源站通过浏览器进行跨域访问。

  • 关闭：关闭跨域策略后，您的服务器资源禁止被任意第三方源站通过浏览器进行跨域访问。

允许的访问来源

设置允许通过浏览器访问服务器资源的站点。参数输入规则如下：

  • 允许所有的访问来源：*。

  • 允许指定根域名的访问来源：*.example.com。

  • 允许多个具体的访问来源：以http://或https://开头，并且以回车分隔。

说明

该参数作用于Access-Control-Allow-Origin头部。当客户端请求的Origin头部匹配上任意您设置的允许的访问来源，跨域响应的Access-Control-Allow-Origin将会被设置为客户端请求的Origin头部。

允许的方法

选择跨域访问时允许的HTTP方法。常见的方法有GET、POST、PUT、DELETE、HEAD、OPTIONS和PATCH。

说明

该参数作用于Access-Control-Allow-Methods头部。

允许的请求头部

除了浏览器内置的基础Header，设置跨域访问时允许的Header。参数输入规则如下：

  • 允许所有的请求头部：*。

  • 允许多个具体的请求头部：输入具体的请求头部，并以回车分隔。

说明

该参数作用于Access-Control-Allow-Headers头部。

允许的响应头部

允许浏览器、JavaScript脚本访问的响应头部。参数输入规则如下：

  • 允许所有的响应头部：*。

  • 允许多个具体的响应头部：输入具体的响应头部，并以回车分隔。

说明

该参数作用于Access-Control-Expose-Headers头部。

允许携带凭证

跨域访问时是否允许携带凭证信息。

说明

该参数作用于Access-Control-Allow-Credentials头部。

预检的过期时间

对于非简单请求，设置OPTIONS预检请求在浏览器的最大缓存时间。

说明

该参数作用于Access-Control-Max-Age头部。

流量复制策略

流量复制策略可以将线上应用流量复制到指定服务。这一功能为系统的仿真测试和问题定位提供了支持，帮助您有效评估应用性能和进行故障排查。

操作步骤

您可在添加策略页面，单击流量复制卡片，在添加策略: 流量复制面板配置相关参数。

参数

描述

开启

API或接口流量复制策略的启用开关。

目标服务

复制的流量要转发的目标服务。

说明

目标服务只支持HTTP/HTTPS协议。

端口

目标服务的端口，您也可以选择动态端口。

说明

动态端口适用于服务端口会动态变化的场景，但不支持有多端口的服务，请勿在多端口场景选择动态端口。

流量复制比例（%）

复制流量的比例，取值为0-100。

说明

若设置为50，则当前API和接口会有50%的流量被复制到目标服务。

超时策略

云原生API网关提供API和接口级别的超时设置，您可以按需为指定API和接口配置网关等待请求响应结果的最大时间。如果网关在设定的时间内未收到后端服务的响应，将向客户端返回一个 HTTP 状态码为 504（Gateway Timeout）的响应结果。

操作步骤

您可在添加策略页面，单击超时卡片，在添加策略：超时面板配置相关参数。

说明

超时策略配置完成且开启后，请根据实际业务验证服务超时规则是否生效。

参数

描述

开启

是否开启超时策略。

  • 开启：网关API或接口超时策略生效。

  • 关闭：网关API或接口超时策略失效。

超时时间

为当前API和接口设置超时时间，单位为秒。

说明

当设置为0或者关闭超时策略时，表示网关会一直等待请求的响应结果。

重试策略

云原生API网关提供API和接口级别的重试设置，可以对出错的请求进行自动重试。您可以根据需求配置重试条件，例如在连接失败、后端服务不可用，或者接收到指定的HTTP状态码时触发请求重试。

API和接口的重试条件

当后端服务返回5xx错误时，云原生API网关按照设置的重试次数对出错的请求自动进行重试。

image

  • HTTP协议的重试条件如下：

    • 5xx：如果后端服务返回任何5xx响应，或者发生连接断开、重置、读取超时事件，云原生API网关将尝试对出错请求进行重试。

      说明

      5xx包含connect-failure和refused-stream的条件。

    • reset：如果发生连接断开、重置、读取超时事件，云原生API网关将尝试对出错请求进行重试。

    • connect-failure：如果请求是由连接断开导致的出错，云原生API网关将尝试对出错请求进行重试。

    • refused-stream：如果后端服务以REFUSED_STREAM错误代码来重置流，云原生API网关将尝试对出错请求进行重试。

    • retriable-status-codes：如果后端服务响应结果的HTTP状态码匹配上您指定的重试状态码，云原生API网关将尝试对该请求进行重试。

      说明

      只有在重试条件中指定了retriable-status-codes，才能使用重试状态码。

  • gRPC协议的重试条件如下：

    • cancelled：如果后端gRPC服务的响应头部中的gRPC状态码为cancelled，云原生API网关将尝试对该请求进行重试。

    • deadline-exceeded：如果后端gRPC服务的响应头部中的gRPC状态码为deadline-exceeded，云原生API网关将尝试对该请求进行重试。

    • internal：如果后端gRPC服务的响应头部中的gRPC状态码为internal，云原生API网关将尝试对该请求进行重试。

    • resource-exhausted：如果后端gRPC服务的响应头部中的gRPC状态码为resource-exhausted，云原生API网关将尝试对该请求进行重试。

    • unavailable：如果后端gRPC服务的响应头部中的gRPC状态码为unavailable，云原生API网关将尝试对该请求进行重试。

操作步骤

您可在添加策略页面，单击重试卡片，在添加策略: 重试面板配置相关参数。

说明

重试策略配置完成且开启后，请根据实际业务验证服务重试规则是否生效。

参数

描述

开启

是否开启重试策略。

  • 开启：网关API或接口重试策略生效。

  • 关闭：网关API或接口重试策略失效。

    关闭重试后，网关内部有默认重试配置，重试次数默认为2次，重试条件默认为connect-failure、refused-stream、unavailable、cancelled和retriable-status-codes。

重试次数

设置对出错请求的最大重试次数。重试次数支持设置0~10次，建议不超过2次。

重试次数设置为0，表示取消重试。

重试条件

选择合适的，支持多选。

重试状态码

对特定HTTP状态码的响应进行重试，支持配置多种HTTP状态码。

重要

重试条件指定retriable-status-codes，才能配置重试状态码。

插件配置

  1. 单击添加插件页签。

  2. 在快捷导航处，选择要安装的插件类型或者搜索插件名称，单击插件卡片：

    • 如果插件未安装，在安装插件的弹出框中单击安装并配置，在启用插件的弹框中配置插件规则，并选择启用状态。

    • 如果插件已安装，在启用插件的弹框中，配置插件规则，并选择启用状态。

  3. 单击确定，返回API的挂载列表，可以看到接口的插件挂载情况和启用状态。

    image

上一篇：接口管理下一篇：配置消费者认证策略