第 5 章 APIcast Policies
APIcast 策略是修改 APIcast 操作方式的功能单元。可以启用、禁用和配置策略,以控制它们如何修改 APIcast。使用策略添加默认 APIcast 部署中不可用的功能。您可以创建自己的策略,或使用 Red Hat 3scale 提供的标准策略。
以下主题提供有关标准 APIcast 策略的信息,创建您自己的自定义 APIcast 策略并创建策略链。
使用策略链控制服务策略。策略链执行以下操作:
- 指定 APIcast 使用的策略
- 为策略 3scale 提供配置信息
- 指定 3scale 加载策略的顺序
红帽 3scale 提供了一种添加自定义策略的方法,但不支持自定义策略。
要使用自定义策略修改 APIcast 的行为,您必须执行以下操作:
- 在 APIcast 中添加自定义策略
- 定义配置 APIcast 策略的策略链
- 将策略链添加到 APIcast
5.1. APIcast 标准策略
Red Hat 3scale 提供以下标准策略:
- 第 5.1.1 节 “3scale Auth 缓存策略”
- 第 5.1.2 节 “3scale Batcher 策略”
- 第 5.1.3 节 “匿名访问策略”
- 第 5.1.4 节 “CORS 请求处理策略”
- 第 5.1.5 节 “echo Policy”
- 第 5.1.6 节 “边缘限制策略”
- 第 5.1.7 节 “标头修改策略”
- 第 5.1.9 节 “liquid 上下文调试策略”
- 第 5.1.10 节 “日志记录策略”
- 第 5.1.14 节 “Prometheus Metrics”
- 第 5.1.11 节 “OAuth 2.0 令牌内省策略”
- 第 5.1.12 节 “Referrer 策略”
- 第 5.1.13 节 “RH-SSO/Keycloak 角色检查策略”
- 第 5.1.15 节 “SOAP 策略”
- 第 5.1.16 节 “上游策略”
- 第 5.1.17 节 “URL 重写策略”
- 第 5.1.18 节 “使用 Captures 策略的 URL 重写”
您可以在 3scale API Management 中 启用和配置 标准策略。
5.1.1. 3scale Auth 缓存策略
3scale 身份验证缓存策略会缓存对 APIcast 发出的身份验证调用。您可以选择操作模式来配置缓存操作。
3scale Auth 缓存在以下模式中可用:
1.Strict - Cache only authorized calls.
"strict"模式仅缓存授权的调用。如果策略在"strict"模式下运行,并且调用失败或被拒绝,策略会使缓存条目失效。如果后端无法访问,则所有缓存的调用都会被拒绝,无论它们缓存的状态如何。
2.Resilient – Authorize according to last request when backend is down.
"弹性"模式会缓存授权和拒绝调用。如果策略在"弹性"模式下运行,则失败的调用不会使现有的缓存条目无效。如果后端变得不可访问,则命中缓存的调用仍会根据缓存的状态继续获得授权或拒绝。
3.Allow - When backend is down, allow everything unless seen before and denied.
"Allow"模式会缓存授权和被拒绝的调用。如果策略在"allow"模式下运行,则缓存的调用根据缓存的状态继续被拒绝或允许。但是,任何新调用都将缓存为授权。
在"允许"模式下操作存在安全隐患。在使用"allow"模式时,请考虑以上问题并进行练习。
4.none - 禁用缓存。
"None"模式禁用缓存。如果您希望策略保持活动状态,但不想使用缓存,则此模式非常有用。
配置属性
属性 | 描述 | 值 | 必需? |
---|---|---|---|
caching_type |
| 数据类型:枚举的字符串 [resilient, strict, allow, none] | 是 |
策略对象示例
{ "name": "caching", "version": "builtin", "configuration": { "caching_type": "allow" } }
有关如何配置策略的详情,请参考文档中的创建策略链 部分。
5.1.2. 3scale Batcher 策略
3scale Batcher 策略提供了标准的 APIcast 授权机制的替代方案,其中为 APIcast 接收的每个 API 请求调用 3scale 后端(Service Management API)。
3scale Batcher 策略通过显著减少到 3scale 后端的请求数量来减少延迟并增加吞吐量。为了达到此目的,此策略会缓存授权状态和批处理使用情况报告。
当 3scale Batcher 策略被启用时,APIcast 会使用以下授权流:
在每个请求中,策略检查是否缓存凭证:
- 如果缓存了凭据,策略将使用缓存的授权状态,而不是调用 3scale 后端。
- 如果没有缓存凭据,策略会调用后端,并使用可配置的生存时间(TTL)来缓存授权状态。
- 策略不立即向 3scale 后端报告与请求对应的使用量,而是累计使用计数器将它们报告到批处理中的后端。单独的线程在单个调用中报告 3scale 后端的总用量计数器,具有可配置的频率。
3scale Batcher 策略提高了吞吐量,但准确性较低。使用限制和当前利用率存储在 3scale 中,APIcast 只能在向 3scale 后端发出调用时获取正确的授权状态。启用 3scale Batcher 策略时,在一个时间段内 APIcast 不会发送调用到 3scale。在此窗口中,调用的应用程序可能会超过定义的限值。
如果吞吐量比速率限制的准确性更重要,则将此策略用于高负载 API。当报告频率和授权 TTL 低于速率限制周期时,3scale Batcher 策略可以带来更好的准确性。例如,如果限制是每天的,并且报告频率和授权 TTL 被配置为几分钟。
3scale Batcher 策略支持以下配置设置:
auths_ttl
:当授权缓存过期时,以秒为单位设置 TTL。当缓存当前调用的授权时,APIcast 将使用缓存的值。在
auths_ttl
参数中设置的时间后,APIcast 会移除缓存并调用 3scale 后端来检索授权状态。-
batch_report_seconds
:设置批处理报告的频率发送到 3scale 后端。默认值为10
秒。
要使用此策略,请在策略链中同时启用 3scale APIcast
和 3scale 批处理器策略
。
5.1.3. 匿名访问策略
匿名访问策略会在没有身份验证的情况下公开一个服务。例如,这对无法适应发送身份验证参数的传统应用程序很有用。匿名策略只支持使用 API Key 和 App Id / App Key 身份验证选项的服务。当为未提供任何凭证的 API 请求启用策略时,APIcast 将授权调用使用策略中配置的默认凭据。若要授权 API 调用,配置有凭据的应用必须存在并且处于活动状态。
使用 Application Plans,您可以配置用于默认凭证的应用程序的速率限值。
在策略链中同时使用这些策略时,您需要将匿名访问策略放在 APIcast 策略的前面。
以下是策略所需的配置属性:
auth_type:从以下其中一个备选中选择一个值,并确保属性与为 API 配置的身份验证选项对应:
- app_id_and_app_key :用于 App ID / App Key 身份验证选项。
- user_key: 用于 API 密钥身份验证选项。
- app_id (仅适用于 app_id_and_app_key auth 类型):如果没有通过 API 调用提供凭证,则将用于授权的应用程序 Id。
- app_key (仅适用于 app_id_and_app_key auth 类型):如果没有通过 API 调用提供凭据,则应用程序的 App Key 用于授权。
- user_key (只适用于 user_key auth_type):API 调用中不提供任何凭据时将用于授权的应用的 API 密钥。
图 5.1. 匿名访问策略
5.1.4. CORS 请求处理策略
通过允许您指定以下指定来控制 CORS 行为,可通过交叉资源共享(CORS)请求处理策略来控制 CORS:
- 允许的标头
- 允许的方法
- 允许凭证
- 允许的源标头
CORS 请求处理策略将阻止所有未指定的 CORS 请求。
当在策略链中使用这两个策略时,您需要将 CORS Request 处理策略放在 APIcast 策略的前面。
配置属性
属性 | 描述 | 值 | 必需? |
---|---|---|---|
allow_headers |
| data type:字符串数组,必须是 CORS 标头 | 否 |
allow_methods |
| data type:枚举字符串的数组 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT] | 否 |
allow_origin |
| 数据类型:字符串 | 否 |
allow_credentials |
| 数据类型:布尔值 | 否 |
策略对象示例
{ "name": "cors", "version": "builtin", "configuration": { "allow_headers": [ "App-Id", "App-Key", "Content-Type", "Accept" ], "allow_credentials": true, "allow_methods": [ "GET", "POST" ], "allow_origin": "https://example.com" } }
有关如何配置策略的详情,请参考文档的创建策略链部分。
5.1.5. echo Policy
echo 策略会向客户端显示传入的请求,以及可选的 HTTP 状态代码。
配置属性
属性 | 描述 | 值 | 必需? |
---|---|---|---|
status | Echo 策略将返回到客户端的 HTTP 状态代码 | 数据类型:整数 | 否 |
exit |
指定回显策略将使用的退出模式。 | data type:枚举字符串 [request, set] | 是 |
策略对象示例
{ "name": "echo", "version": "builtin", "configuration": { "status": 404, "exit": "request" } }
有关如何配置策略的详情,请参考文档的创建策略链部分。
5.1.6. 边缘限制策略
Edge Limiting 策略旨在为发送到后端 API 的流量提供灵活的速率限制,并可与默认的 3scale 授权一起使用。策略支持的用例的一些示例包括:
-
最终用户速率限制:速率受到请求的 Authorization 头中的 JWT 令牌中的 "sub" (subject) 声明值的限制(配置为
{{ jwt.sub }}
)。 - 请求每秒(RPS)速率限制.
- 每个服务的全球速率限值:每个服务应用限制而不是每个应用程序。
- 并发连接限制:设置允许的并发连接数。
5.1.6.1. 限制类型
该策略支持 lua-resty-limit-traffic 库提供的以下类型的限制:
-
leaky_bucket_limiters
:基于基于基于平均请求数和最大突发大小的"leaky_bucket"算法。 -
fixed_window_limiters
: 基于固定的时间窗口(最后 X 秒)。 -
connection_limiters
:基于并发连接数。
您可以通过服务或全局限制来限制任何限制。
5.1.6.2. 限制定义
限制具有一个键,用于对用来定义限制(IP、服务、端点、ID、特定标头等)的实体进行编码。Key 在限制者的 key
参数中指定。
key
是由以下属性定义的对象:
-
名称
:键的名称。它在范围内必须是唯一的。 Scope
:它定义密钥的范围。支持的范围有:-
每个影响一个服务(
service
)的服务范围。 -
影响所有服务(
global
)的全局范围。
-
每个影响一个服务(
name_type
: 它定义如何评估"name"值:-
纯文本(
plain
) -
Liquid(
liquid
)
-
纯文本(
每个限制也有一些参数因类型而异:
leaky_bucket_limiters
:rate
,burst
.-
速率
:它定义每秒可进行的请求数量,而没有延迟。 -
burst
:它定义每秒可以超过允许的速率的请求数。对于超过允许率(由rate
指定)的请求引入人工延迟。在超过burst
中定义的每秒请求数后,请求将被拒绝。
-
-
fixed_window_limiters
:count
,window
.计数
定义了在窗口
中定义的每秒数发出的请求数量。 connection_limiters
:conn
、burst
、delay
.-
conn
:定义允许的最大并发连接数。它允许通过每秒burst
连接超过该数量。 -
delay
:这是延迟超过限制的连接的秒数。
-
例子
每分钟允许 10 个请求到 service_A:
{ "key": { "name": "service_A" }, "count": 10, "window": 60 }
允许 100 个连接,带有 10 个突发,延迟为 1 秒:
{ "key": { "name": "service_A" }, "conn": 100, "burst": 10, "delay": 1 }
您可以为每个服务定义多个限制。如果定义了多个限制,则在至少达到一个限值时请求可以被拒绝或延迟。
5.1.6.3. 移动模板
Edge Limiting 策略允许通过在键中支持 Liquid 变量来指定动态密钥的限制。对于这个,键的 name_type
参数必须设置为 "liquid",而 name
参数则可使用 Liquid 变量。示例:{ { remote_addr }}
用于客户端 IP 地址,或者 {{ jwt.sub }}
用于 JWT 令牌的"sub"声明。
例如:
{ "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" }, "count": 10, "window": 60 }
有关 Liquid 支持的详情请参考 第 6.1 节 “在策略中使用变量和过滤器”。
5.1.6.4. 应用条件
该条件定义 API 网关何时应用限制器。您必须在每个限制器的 condition
属性中至少指定一个操作。
condition
由以下属性定义:
-
combine_op
.它是应用于操作列表的布尔值运算符。支持以下两个值:或
和
。 operations
。它是需要评估的条件列表。每个操作都由一个具有以下属性的对象表示:-
left
:操作的左侧。 -
left_type
:如何评估左
属性(解释或静止)。 -
正确
:操作的正确部分。 -
right_type
:如何评估正确的
属性(解释或查询)。 -
op
:在左侧和右部分之间应用的 Operator。支持以下两个值:==
(等于)和!=
(不等于)。
-
例如:
"condition": { "combine_op": "and", "operations": [ { "op": "==", "right": "GET", "left_type": "liquid", "left": "{{ http_method }}", "right_type": "plain" } ] }
5.1.6.5. 配置存储
默认情况下,Edge 限制策略将 OpenResty 共享字典用于速率限制计数器。但是,可以使用外部 Redis 服务器而不是共享字典。这在使用多个 APIcast 实例时很有用。Redis 服务器可以使用 redis_url
参数进行配置。
5.1.6.6. 错误处理
限制器支持以下参数来配置错误的处理方式:
limits_exceeded_error
允许配置在超过配置的限制时返回到客户端的错误状态代码和消息。应配置以下参数:-
status_code
:超过限制时请求的状态代码。默认:429
。 error_handling
:如何处理错误。-
退出
: "Respond with an error"。 -
日志
:"记录请求通过,仅输出日志"
-
-
configuration_error
允许配置错误状态代码,并在配置错误时返回到客户端的消息。应配置以下参数:-
status_code
:配置问题时的状态代码。默认:500。 error_handling
:如何处理错误。-
退出
: "Respond with an error"。 -
日志
:"记录请求通过且仅输出日志"。
-
-
5.1.7. 标头修改策略
标头修改策略允许您修改现有标头,或者定义额外的标头以添加到或从传入的请求或响应中删除。您可以修改响应和请求标头。
Header 修改策略支持以下配置参数:
-
request
: 应用到请求标头的操作列表 -
response
:应用到响应标头的操作列表
每个操作都由以下参数组成:
-
op
:指定要应用的操作。add
操作会为现有标头添加一个值。这个set
操作会创建一个标头和值,如果已存在该标头的值,则会覆盖现有的标头值。push
操作会创建一个标头和值,但如果已存在,则不会覆盖现有的标头值。相反,push
会将值添加到现有标头中。delete
操作会删除标头。 -
标题
:指定要创建的标头或修改,并且可以用作标头名称(如Custom-Header
)的任何字符串。 -
value_type
:定义如何评估标题值,可以是plain
(纯文本)或liquid
(Liquid 模板)。更多信息请参阅 第 6.1 节 “在策略中使用变量和过滤器”。 -
value
: 指定用于标头的值。对于值类型"liquid",值应当采用{{ variable_from_context }}
格式。删除时不需要.
策略对象示例
{ "name": "headers", "version": "builtin", "configuration": { "response": [ { "op": "add", "header": "Custom-Header", "value_type": "plain", "value": "any-value" } ], "request": [ { "op": "set", "header": "Authorization", "value_type": "plain", "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" }, { "op": "set", "header": "Service-ID", "value_type": "liquid", "value": "{{service.id}}" } ] } }
有关如何配置策略的详情,请参考文档中的创建策略链 部分。
5.1.8. IP 检查策略
IP 检查策略用于根据 IP 列表拒绝或允许请求。
配置属性
属性 | 描述 | 数据类型 | 必需? |
---|---|---|---|
check_type |
|
字符串,必须是 | 是 |
ips |
| 字符串数组,必须是有效的 IP 地址 | 是 |
error_msg |
| 字符串 | 否 |
client_ip_sources |
|
字符串数组,有效选项为 | 否 |
策略对象示例
{ "name": "ip_check", "configuration": { "ips": [ "3.4.5.6", "1.2.3.0/4" ], "check_type": "blacklist", "client_ip_sources": ["X-Forwarded-For", "X-Real-IP", "last_caller"], "error_msg": "A custom error message" } }
有关如何配置策略的详情,请参考文档的创建策略链部分。
5.1.9. liquid 上下文调试策略
Liquid Context Debug 策略仅用于开发环境中而不是生产环境中的调试用途。
此策略使用 JSON 响应 API 请求,其包含上下文中可用的对象和值,并可用于评估 Liquid 模板。与 3scale APIcast 或 上游策略结合使用时,必须将 Liquid Context Debug 放置在策略链中才能正常工作。为避免循环引用,该策略仅包含重复的对象,并将其替换为 stub 值。
启用策略时 APIcast 返回的值示例:
{ "jwt": { "azp": "972f7b4f", "iat": 1537538097, ... "exp": 1537574096, "typ": "Bearer" }, "credentials": { "app_id": "972f7b4f" }, "usage": { "deltas": { "hits": 1 }, "metrics": [ "hits" ] }, "service": { "id": "2", ... } ... }
5.1.10. 日志记录策略
日志记录策略允许单独启用或禁用 APIcast(NGINX)访问日志。默认情况下,策略链中不启用此策略。
此策略仅支持 enable_access_logs
配置参数。要禁用服务的访问日志记录,启用策略,取消选择 enable_access_logs
参数,然后单击 Submit
按钮。要启用访问日志,请选择 enable_access_logs
参数或禁用 Logging 策略。
您可以将 Logging 策略与访问日志位置的全局设置合并。设置 APICAST_ACCESS_LOG_FILE
环境变量,以配置 APIcast 访问日志的位置。默认情况下,此变量设置为 /dev/stdout
,这是标准输出设备。有关全局 APIcast 参数的详情,请参考 ???。
5.1.11. OAuth 2.0 令牌内省策略
OAuth 2.0 Token Introspection 策略允许使用令牌签发者(Red Hat Single Sign-On)的 Token Introtion Endpoint(Red Hat Single Sign-On)验证选项来验证用于通过 OpenID Connect 身份验证选项的 JSON Web Token Token 令牌(JWT)令牌。
APIcast 支持 auth_type
字段中的以下身份验证类型,以确定 Token Introspection Endpoint 和调用此端点时使用的凭证 APIcast:
use_3scale_oidc_issuer_endpoint
使用这个设置,APIcast 使用在 Service Integration 页面中配置的 OpenID Connect Issuer 设置中的客户端凭证(客户端 ID 和客户端 Secret)和令牌内省端点。
APIcast 从
token_introspection_endpoint
字段发现 Token Introspection 端点,.well-known/openid-configuration
端点返回。例 5.1. 身份验证类型设置为
use_3scale_oidc_issuer_endpoint
如果身份验证类型被设置为
use_3scale_oidc_issuer_endpoint
,则是一个配置示例:"policy_chain": [ … { "name": "apicast.policy.token_introspection", "configuration": { "auth_type": "use_3scale_oidc_issuer_endpoint" } } … ],
client_id+client_secret
这个选项允许您指定不同的令牌内省端点,以及客户端 ID 和客户端 Secret APIcast 用来请求令牌信息。
使用这个选项时,请设置以下配置参数:
-
client_id
:为令牌内省端点设置客户端 ID。 -
client_secret
:为令牌内省端点设置客户端 Secret。 introspection_url
:设置 Introspection Endpoint URL。例 5.2. 身份验证类型设置为
client_id+client_secret
如果身份验证类型被设置为
client_id+client_secret
,则如下是配置示例:"policy_chain": [ … { "name": "apicast.policy.token_introspection", "configuration": { "auth_type": "client_id+client_secret", "client_id": "myclient", "client_secret": "mysecret", "introspection_url": "http://red_hat_single_sign-on/token/introspection" } } … ],
-
无论 auth_type
字段中的设置是什么,APIcast 都会使用 Basic Authentication 来授权 Token Introspection 调用(Authorization: Basic <token>
头,其中 <token> 是 Base64 编码的 <client_id>:<client_secret> 设置)。
Token Introspection Endpoint 的响应中包含 active
属性。APIcast 检查此属性的值。根据属性的值,APIcast 授权或拒绝调用:
-
true
:调用已被授权 -
false
: 调用被拒绝,且Authentication Failed
错误
该策略允许缓存令牌,以避免在相同 JWT 令牌的每个调用中调用 Token Introspection Endpoint。要为 Token Introspection Policy 启用令牌缓存,请将 max_cached_tokens
字段设置为从 0
(禁用该功能)到 10000
直接的值。另外,您可以在 max_ttl_tokens
字段中将令牌的值从 1
设置为 3600
秒。
5.1.12. Referrer 策略
Referrer 策略启用了 Referrer Filtering 功能。当在服务策略链中启用策略时,APIcast 会在 referrer
参数中将后续请求的 Referer
策略发送到 Service Management API(AuthRep 调用)。有关如何过滤工作的更多信息,请参阅 身份验证模式 中的" 引用器过滤 "部分。
5.1.13. RH-SSO/Keycloak 角色检查策略
此策略在与 OpenID Connect 身份验证选项一起使用时添加角色检查。此策略会验证红帽单点登录发布的访问令牌中的 realm 角色和客户端角色。当您要为每一个客户端的资源或 3Scale 添加角色检查时,会指定 realm 角色。
以下是两种角色类型,用于检查 类型 属性是否在策略配置中指定:
- 白名单 (默认):当使用 白名单 时,APIcast 将检查 JWT 令牌中是否存在指定的范围,并在 JWT 中没有范围时拒绝调用。
- blacklist :当使用 黑名单 时,如果 JWT 令牌包含黑名单范围,APIcast 将拒绝调用。
同一策略中无法同时配置 blacklist 和 whitelist 检查,但您可以在 APIcast 策略链中添加多个 RH-SSO/Keycloak 角色检查 策略链。
您可以通过策略配置的 scopes 属性配置范围列表。
每个 scope 对象具有以下属性:
- 资源 :角色控制的资源(端点)。这个格式与映射规则相同。模式从字符串开头匹配,若要完全匹配,您必须在末尾附加 $。
resource_type :这定义了 资源 值的评估方式。
- 以纯文本(plain)形式:以纯文本形式评估 资源 值。示例: /api/v1/products$.
- 作为 Liquid 文本(liquid):允许在 资源 值中使用 Liquid。示例: /resource_{{ jwt.aud }} 管理对资源的访问,包括客户端 ID(包含在 JWT 仲裁 声明中)。
realm_roles :使用它来检查 realm 角色(请参阅 Red Hat Single Sign-On 文档中的 Realm 角色 )。
域角色存在于红帽单点登录发布的 JWT 中。
"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }
策略中必须指定实际角色。
"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]
以下是 realm_roles 数组中每个对象的可用属性:
- name :指定角色的名称。
- name_type :定义必须如何评估名称;它可以是 纯 的 或 liquid (与 resource_type的相同)。
client_roles :使用 client_roles 检查客户端命名空间中的特定访问角色(请参阅 Red Hat Single Sign-On 文档中的客户端角色 )。
客户端角色存在于 JWT 中的 resource_access 声明下。
"resource_access": { "<client_A>": { "roles": [ "<client_role_A>", "<client_role_B>" ] }, "<client_B>": { "roles": [ "<client_role_A>", "<client_role_B>" ] } }
指定策略中的客户端角色。
"client_roles": [ { "name": "<client_role_A>", "client": "<client_A>" }, { "name": "<client_role_B>", "client": "<client_A>" }, { "name": "<client_role_A>", "client": "<client_B>" }, { "name": "<client_role_B>", "client": "<client_B>" } ]
以下是 client_roles 数组中每个对象的可用属性:
- name :指定角色的名称。
- name_type :定义必须如何评估 name 值;它可以是 纯 的 或 liquid (与 resource_type的相同)。
- client :指定角色的客户端。如果未定义,此策略将 aud 声明用作客户端。
- client_type: 定义 client 值如何被评估。可以是 plain 或 liquid(与 resource_type 相同)。
5.1.14. Prometheus Metrics
Prometheus是一个独立的开源系统监视和警报工具包。
在这个 Red Hat 3scale 版本中,不支持 Prometheus 安装和配置。另外,您可以使用 Prometheus 的社区版本 视觉化 API 服务的指标和警报。
Prometheus 指标可用性
以下部署选项提供了与 Prometheus 的 APIcast 集成:
- 自我管理的 APIcast(包括托管或内部 API 管理器)
- 内置 APIcast 内部
托管 API Manager 和托管的 APIcast 不提供与 Prometheus 的 APIcast 集成。
Prometheus metrics 列表
以下指标始终可用:
指标 | 描述 | 类型 | 标签 |
---|---|---|---|
nginx_http_connections | HTTP 连接数 | gauge | state(accepted,active,handled,reading,total,waiting,writing) |
nginx_error_log | APIcast 错误 | 计数 | level(debug,info,notice,warn,error,crit,alert,emerg) |
openresty_shdict_capacity | worker 共享字典的能力 | gauge | dict(one for every dictionary) |
openresty_shdict_free_space | worker 共享字典的可用空间 | gauge | dict(one for every dictionary) |
nginx_metric_errors_total | 管理指标的 Lua 库错误数 | 计数 | - |
total_response_time_seconds | 向客户端发送响应所需的时间(以秒为单位) | histogram | - |
upstream_response_time_seconds | 来自上游服务器的响应时间(以秒为单位) | histogram | - |
upstream_status | 来自上游服务器的 HTTP 状态 | 计数 | status |
threescale_backend_calls | 授权并报告请求到 3scale 后端(Apisonator) | 计数 | endpoint(authrep, auth, report), status(2xx, 4xx, 5xx) |
只有在使用 3scale Batcher 策略时,以下指标才可用:
指标 | 描述 | 类型 | 标签 |
---|---|---|---|
batching_policy_auths_cache_hits | 按 3scale 批处理策略的 auths 缓存中的内容 | 计数 | - |
batching_policy_auths_cache_misses | 3scale 批处理策略的 auths 缓存中丢失 | 计数 | - |
没有值的指标
如果指标没有值,则指标会被隐藏。例如,如果 nginx_error_log
没有报告错误,则不会显示 nginx_error_log
指标。只有当它有值时才可见。
5.1.15. SOAP 策略
SOAP 策略与 HTTP 请求的 SOAPAction 或 Content-Type 标头中提供的 SOAP 操作 URI 匹配策略中指定的映射规则。
配置属性
属性 | 描述 | 值 | 必需? |
---|---|---|---|
pattern |
此 | 数据类型:字符串 | 是 |
metric_system_name |
| 数据类型:字符串,必须是一个有效的 metric | 是 |
策略对象示例
{ "name": "soap", "version": "builtin", "configuration": { "mapping_rules": [ { "pattern": "http://example.com/soap#request", "metric_system_name": "soap", "delta": 1 } ] } }
有关如何配置策略的详情,请参考文档的创建策略链部分。
5.1.16. 上游策略
通过 Upstream 策略,您可以使用正则表达式来解析主机请求标头,并将私有基本 URL 中定义的上游 URL 替换为不同的 URL。
例如:
具有 regex /foo
的策略和 URL 字段 newexample.com
将 URL https://www.example.com/foo/123/
替换为 newexample.com
策略链参考:
属性 | 描述 | 值 | 必需? |
---|---|---|---|
regex |
| 数据类型:字符串,必须是一个有效的正则表达式语法 | 是 |
url |
使用 | 数据类型:字符串,确定这是有效的 URL | 是 |
策略对象示例
{ "name": "upstream", "version": "builtin", "configuration": { "rules": [ { "regex": "^/v1/.*", "url": "https://api-v1.example.com", } ] } }
有关如何配置策略的详情,请参考文档的创建策略链部分。
5.1.17. URL 重写策略
URL 重写策略允许您修改请求的路径和查询字符串。
当与 3scale APIcast 政策结合使用时,如果将 URL 重新编写策略放在策略链中的 3scale APIcast 策略之前,APIcast 映射规则将应用到修改后的路径。如果在 APIcast 链中的 APIcast 后放置了 URL 重写策略,则映射规则将应用到原始路径。
该策略支持以下两组操作:
-
commands
:要应用的命令列表来重写请求的路径。 -
query_args_commands
:要应用的命令列表来重写请求的查询字符串。
5.1.17.1. 重写路径的命令
以下是 commands
列表中每个命令的配置参数,其中包括:
-
op
:要应用的操作。可用的选项包括:sub
和gsub
。sub
操作仅用您指定的正则表达式替换第一个匹配项。gsub
操作会将所有匹配项替换为您指定的正则表达式。请参阅有关 sub 和 gsub 操作的文档。 -
正则表达式
:要匹配的与 Perl 兼容的正则表达式。 -
替换
:替换在匹配项中使用的 : 替换字符串。 -
Options(可选):定义正则表达式的执行方式
的选项
。有关可用选项的详情,请查看 OpenResty Lua 模块项目文档中的 ngx.re.match 部分。 -
break
(可选):当启用复选框设置为 true 时,如果命令重新编写该 URL,它将是应用的最后一个,并且列表中的所有 posterior 命令将被丢弃。
5.1.17.2. 重写查询字符串的命令
以下是 query_args_commands
列表中每个命令由以下部分组成的配置参数:
op
: 操作要应用到查询参数。可用的选项如下:-
添加
: 为现有参数添加一个值。 -
设置
:在未设置时创建 arg,并在设置时替换其值。 -
push
:在未设置时创建 arg,并在设置时添加值。 -
删除
:删除 arg。
-
-
ARG
:用于操作的查询参数名称。 -
value
:指定用于查询参数的值。对于值类型"liquid",值应当采用{{ variable_from_context }}
格式。对于delete
操作,不考虑该值。 -
value_type
(可选): 定义查询参数值的评估方式,可以是plain
(纯文本)或liquid
(作为 Liquid 模板评估)。更多信息请参阅 第 6.1 节 “在策略中使用变量和过滤器”。如果没有指定,则默认使用类型"plain"。
示例
URL 重写策略配置如下:
{ "name": "url_rewriting", "version": "builtin", "configuration": { "query_args_commands": [ { "op": "add", "arg": "addarg", "value_type": "plain", "value": "addvalue" }, { "op": "delete", "arg": "user_key", "value_type": "plain", "value": "any" }, { "op": "push", "arg": "pusharg", "value_type": "plain", "value": "pushvalue" }, { "op": "set", "arg": "setarg", "value_type": "plain", "value": "setvalue" } ], "commands": [ { "op": "sub", "regex": "^/api/v\\d+/", "replace": "/internal/", "options": "i" } ] }
发送到 APIcast 的原始请求 URI:
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
应用 URL 重写后 APIcast 发送到 API 后端的 URI:
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
应用以下转换:
-
子字符串
/api/v1/
匹配唯一的路径重写命令,它被/internal/
替换。 -
已删除
user_key
查询参数。 -
值
pushvalue
作为pusharg
查询参数的额外值添加。 -
查询参数
setarg
的original
值替换为配置的值setvalue
。 -
命令
add
没有被应用,因为原始 URL 中不存在查询参数addarg
。
有关如何配置策略的详情,请参考文档中的创建策略链 部分。
5.1.18. 使用 Captures 策略的 URL 重写
使用 Captures 策略的 URL Rewriting 是 第 5.1.17 节 “URL 重写策略” 策略的替代,并允许在将 API 请求传递给 API 后端前重写 API 请求的 URL。
URL 使用 Captures 策略检索 URL 中的参数,并在重写 URL 中使用其值。
该策略支持 transformations
配置参数。这是一个对象列表,用于描述将哪些转换应用到请求 URL。每个调整对象由两个属性组成:
-
match_rule
:此规则与传入请求 URL 匹配。它可以包含{nameOfArgument}
格式的命名参数;这些参数可以在重写 URL 中使用。将 URL 与match_rule
进行比较,作为正则表达式。匹配指定参数的值必须只包含以下字符(在 PCRE regex 表示法中):[\w-.~%!$&'()*+,;=@:]+
。可以在match_rule
表达式中使用其他 regex 令牌,如^
表示字符串开头,$
代表字符串末尾。 -
template
:使用重写原始 URL 的 URL 模板;它可以使用match_rule
中的指定参数。
原始 URL 的查询参数与 template
中指定的查询参数合并。
示例
使用 Captures 的 URL 重写如下:
{ "name": "rewrite_url_captures", "version": "builtin", "configuration": { "transformations": [ { "match_rule": "/api/v1/products/{productId}/details", "template": "/internal/products/details?id={productId}&extraparam=anyvalue" } ] } }
发送到 APIcast 的原始请求 URI:
https://api.example.com/api/v1/products/123/details?user_key=abc123secret
应用 URL 重写后 APIcast 发送到 API 后端的 URI:
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123