第 4 章 APIcast 策略

在管理门户中，您可以为每个 3scale API 产品启用一个或多个策略。

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"模式下运行，则缓存的调用根据缓存的状态继续被拒绝或允许。但是，任何新调用都将缓存为授权。

4.none - 禁用缓存。

"None"模式禁用缓存。如果您希望策略保持活动状态，但不想使用缓存，则此模式非常有用。

配置属性

策略对象示例

{
  "name": "caching",
  "version": "builtin",
  "configuration": {
    "caching_type": "allow"
  }
}

有关如何配置策略的详情，请参考文档中的创建策略链 部分。

3scale Batcher 策略提供了标准的 APIcast 授权机制的替代方案，其中为 APIcast 接收的每个 API 请求调用 3scale 后端(Service Management API)。

3scale Batcher 策略会缓存授权状态和批处理使用报告，从而显著减少请求数到 3scale 后端。借助 3scale 批处理器策略，您可以通过降低延迟并提高吞吐量来提高 APIcast 性能。

当 3scale Batcher 策略被启用时，APIcast 会使用以下授权流：

3scale Batcher 策略提高了吞吐量，但准确性较低。使用限制和当前利用率存储在 3scale 中，APIcast 只能在向 3scale 后端发出调用时获取正确的授权状态。启用 3scale Batcher 策略时，在一个时间段内 APIcast 不会发送调用到 3scale。在这个时间窗内，发出调用的应用可能会超过定义的限值。

如果吞吐量比速率限制的准确性更重要，则将此策略用于高负载 API。当报告频率和授权 TTL 低于速率限制周期时，3scale Batcher 策略可以带来更好的准确性。例如，如果限制是每天的，并且报告频率和授权 TTL 被配置为几分钟。

3scale Batcher 策略支持以下配置设置：

3scale 推荐器策略启用了 推荐过滤器功能。当服务策略链中启用策略时，APIcast 将 3scale Referencerer 策略的值发送到 Service Management API，作为向上方 AuthRep 调用。3scale Referencerer 策略的值在调用中的 referrer 参数中发送。

有关 Referrer Filtering 如何工作的更多信息，请参阅身份验证模式下的 Referrer Filtering 部分。

匿名访问策略会公开一项服务，无需身份验证。例如，这对无法适应发送身份验证参数的传统应用程序很有用。匿名访问策略只支持使用 API Key 和 App Id / App Key 身份验证选项的服务。当为未提供任何凭证的 API 请求启用策略时，APIcast 将授权调用使用策略中配置的默认凭据。若要授权 API 调用，配置有凭据的应用必须存在并且处于活动状态。

使用 Application Plans，您可以配置用于默认凭证的应用程序的速率限值。

以下是策略所需的配置属性：

图 4.1. 匿名访问策略

您可以使用 Camel 服务策略定义 HTTP 代理，其中 3scale 流量通过定义的 Apache Camel 代理发送。在这种情况下，Camel 充当反向 HTTP 代理，APIcast 将流量发送到 Camel，然后 Camel 会将流量发送到 API 后端。

以下示例显示了流量流：

发送到 3scale 后端的所有 APIcast 流量都不使用 Camel 代理。此策略仅适用于 Camel 代理以及 APIcast 和 API 后端之间的通信。

如果要通过代理发送所有流量，则必须使用 HTTP_PROXY 环境变量。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.camel",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8080/",
          "http_proxy": "http://192.168.15.103:8080/",
          "https_proxy": "http://192.168.15.103:8443/"
      }
    }
]

如果未定义 http_proxy 或 https_proxy，则使用 all_proxy 值。

有关使用通用 HTTP 代理策略的详情，请参考 第 4.1.25 节 “代理服务”。

条件策略与其他 APIcast 策略不同，因为它包含一系列策略。它定义在每个 nginx 阶段 评估的条件，如 访问、重写 和日志 等。当条件为 true 时，条件策略会为其链中包含的每个策略运行该阶段。

以下示例假定 Conditional Policy 定义以下条件： 请求方法为 POST。

APIcast --> Caching --> Conditional --> Upstream

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

在这种情况下，当请求是 POST 时，每个阶段的执行顺序如下：

如果没有 POST 请求，每个阶段的执行顺序如下：

本例检查请求路径是否为 /example_path ：

{
  "left": "{{ uri }}",
  "left_type": "liquid",
  "op": "==",
  "right": "/example_path",
  "right_type": "plain"
}

左和右边的运算对象都可以评估为 liquid 或纯字符串。纯文本字符串是默认值。

您可以将操作与 and 或 or 组合使用。此配置检查与上例相同，外加 Backend 标头值：

{
  "operations": [
    {
      "left": "{{ uri }}",
      "left_type": "liquid",
      "op": "==",
      "right": "/example_path",
      "right_type": "plain"
    },
    {
      "left": "{{ headers['Backend'] }}",
      "left_type": "liquid",
      "op": "==",
      "right": "test_upstream",
      "right_type": "plain"
    }
  ],
  "combine_op": "and"
}

如需了解更多详细信息，请参阅 策略配置模式。

更新的变量列表可在此处找到： ngx_variable.lua

这个示例在请求的 Backend 标头是 staging 时执行上游策略：

{
   "name":"conditional",
   "version":"builtin",
   "configuration":{
      "condition":{
         "operations":[
            {
               "left":"{{ headers['Backend'] }}",
               "left_type":"liquid",
               "op":"==",
               "right":"staging"
            }
         ]
      },
      "policy_chain":[
         {
            "name":"upstream",
            "version": "builtin",
            "configuration":{
               "rules":[
                  {
                     "regex":"/",
                     "url":"http://my_staging_environment"
                  }
               ]
            }
         }
      ]
   }
}

内容缓存策略允许您根据自定义条件启用和禁用缓存。这些条件只能应用于客户端请求，因为策略中无法使用上游响应。

当内容缓存策略位于策略链中时，APIcast 会在发送上游请求前将 HEAD 请求发送到 GET 请求。如果您不想进行此转换，请不要将内容缓存策略添加到策略链中。

如果发送了 cache-control 标头，它将优先于 APIcast 设定的超时。

如果 Method 是 GET，则以下示例配置将缓存响应。

{
  "name": "apicast.policy.content_caching",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "cache": true,
        "header": "X-Cache-Status-POLICY",
        "condition": {
          "combine_op": "and",
          "operations": [
            {
              "left": "{{method}}",
              "left_type": "liquid",
              "op": "==",
              "right": "GET"
            }
          ]
        }
      }
    ]
  }
}

通过允许您指定以下指定来控制 CORS 行为，可通过交叉资源共享(CORS)请求处理策略来控制 CORS：

CORS 请求处理策略将阻止所有未指定的 CORS 请求。

配置属性

策略对象示例

{
  "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",
   "max_age" : 200
  }
}

有关如何配置策略的详情，请参考 3scale 管理门户中的修改策略链。

自定义 Metrics 策略会添加可用性，以在上游 API 发送的响应后添加指标。此策略的主要用例是根据响应代码状态、标头或不同的 NGINX 变量添加指标。

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "error",
        "increment": "{{ resp.headers['increment'] }}",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "400",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

如果上游 API 返回 200 状态，则此策略使用 status_code 信息递增 hits 指标：

{
  "name": "apicast.policy.custom_metrics",
  "configuration": {
    "rules": [
      {
        "metric": "hits_{{status}}",
        "increment": "1",
        "condition": {
          "operations": [
            {
              "right": "{{status}}",
              "right_type": "liquid",
              "left": "200",
              "op": "=="
            }
          ],
          "combine_op": "and"
        }
      }
    ]
  }
}

Echo 策略将传入请求打印回客户端，以及可选的 HTTP 状态代码。

配置属性

策略对象示例

{
  "name": "echo",
  "version": "builtin",
  "configuration": {
    "status": 404,
    "exit": "request"
  }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

Edge Limiting 策略旨在为发送到后端 API 的流量提供灵活的速率限制，并可与默认的 3scale 授权一起使用。策略支持的用例的一些示例包括：

您可以通过服务或全局限制来限制任何限制。

key 是由以下属性定义的对象：

每个限制也具有一些因类型而异的参数：

您可以为每个服务定义多个限制。如果定义了多个限制，则在至少达到一个限值时请求可以被拒绝或延迟。

{
  "key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
  "count": 10,
  "window": 60
}

有关 Liquid 支持的详情请参考 第 5.1 节 “在策略中使用变量和过滤器”。

condition 由以下属性定义：

"condition": {
  "combine_op": "and",
  "operations": [
    {
      "op": "==",
      "right": "GET",
      "left_type": "liquid",
      "left": "{{ http_method }}",
      "right_type": "plain"
    }
  ]
}

标头修改策略允许您修改现有标头，或者定义额外的标头以添加到或从传入的请求或响应中删除。您可以修改响应和请求标头。

Header 修改策略支持以下配置参数：

每个操作都由以下参数组成：

策略对象示例

{
  "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}}"
      }
    ]
  }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

作为 API 供应商，您可以将 HTTP Status Code Overwrite 策略添加到 API 产品中。此策略允许您将上游响应代码改为您指定的响应代码。3scale 将 HTTP Status Code Overwrite 策略应用到从上游服务发送的响应代码。换句话说，当 3scale 公开的 API 返回不适合您情况的代码时，您可以配置 HTTP Status Response Code Overwrite 策略，将代码更改为对应用程序有意义的响应代码。

在策略链中，任何生成要更改的响应代码的策略都必须在 HTTP 状态代码 Overwrite 策略之前。如果没有生成您要更改的 Status Codes 的策略，则 HTTP Status Code Overwrite 策略的策略链位置无关紧要。

在管理门户中，将 HTTP Status Code Overwrite 策略添加到产品的策略链中。在策略链中，单击策略以指定您要更改的上游响应代码以及您要返回的响应代码。单击您要覆盖的每个额外上游响应代码的加号。例如，您可以使用 HTTP 状态代码覆盖策略将上游 201、"Created"、响应代码改为 200，"OK"，响应代码。

在超过内容限制时，响应代码可能要更改的另一个示例就是响应。当响应代码为 414 （请求 URI 过长）时，上游可能会返回 413(载荷过大)。

在管理门户中添加 HTTP Status Code Overwrite 策略的一种替代方案是将 3scale API 与策略链配置文件搭配使用。

{
  "name": "statuscode_overwrite",
  "version": "builtin",
  "configuration": {
    "http_statuses": [
      {
        "upstream": 200,
        "apicast": 201
      },
      {
        "upstream": 413,
        "apicast": 414
      }
    ]
  }
}

HTTP2 Endpoint 策略启用发送请求的消费者应用之间的 HTTP/2 协议连接。当 HTTP2 Endpoint 策略在产品的策略链中时，整个通信流（从向上游服务发出请求的消费者应用程序到 APIcast）可以使用 HTTP/2 协议。

当 HTTP2 端点策略位于策略链中时：

IP 检查策略用于根据 IP 列表拒绝或允许请求。

配置属性

策略对象示例

{
  "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"
  }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

JWT 声明基于 JSON Web Token(JWT)声明，您可以通过定义新规则来阻止资源目标和方法。

如果 JWT Claim Check 策略正在阻止资源和方法，该策略也会验证 JWT 操作。另外，如果方法资源不匹配，则请求将继续至后端 API。

Example:如果是 GET 请求，JWT 需要将角色声明设为 admin，否则请求将被拒绝。另一方面，任何非 GET 请求都不会验证 JWT 操作，因此允许 POST 资源而无需 JWT 约束。

{
  "name": "apicast.policy.jwt_claim_check",
  "configuration": {
      "error_message": "Invalid JWT check",
      "rules": [
          {
              "operations": [
                  {"op": "==", "jwt_claim": "role", "jwt_claim_type": "plain", "value": "admin"}
              ],
              "combine_op":"and",
              "methods": ["GET"],
              "resource": "/resource",
              "resource_type": "plain"
          }
      ]
  }
}

此策略使用 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",
        ...
      }
      ...
    }

Logging 策略有两个目的：

您可以将 Logging 策略与访问日志位置的全局设置合并。设置 APICAST_ACCESS_LOG_FILE 环境变量，以配置 APIcast 访问日志的位置。默认情况下，此变量设置为 /dev/stdout，这是标准输出设备。有关全局 APIcast 参数的详情，请参考 第 7 章 APIcast 环境变量。

另外，日志记录策略具有以下功能：

local cjson = require('cjson')
local PolicyChain = require('apicast.policy_chain')
local policy_chain = context.policy_chain

local logging_policy_config = cjson.decode([[
{
  "enable_access_logs": false,
  "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}"
}
]])

policy_chain:insert( PolicyChain.load_policy('logging', 'builtin', logging_policy_config), 1)

return {
  policy_chain = policy_chain,
  port = { metrics = 9421 },
}

docker run --name apicast --rm -p 8080:8080 \
    -v $(pwd):/config \
    -e APICAST_ENVIRONMENT=/config/custom_env.lua \
    -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@ADMIN_PORTAL_DOMAIN \
    quay.io/3scale/apicast:master

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "[{{time_local}}] {{host}}:{{server_port}} {{remote_addr}}:{{remote_port}} \"{{request}}\" {{status}} {{body_bytes_sent}} ({{request_time}}) {{post_action_impact}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.serializable.name}}",
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "enable_json_logs": true,
    "json_object_config": [
      {
        "key": "host",
        "value": "{{host}}",
        "value_type": "liquid"
      },
      {
        "key": "time",
        "value": "{{time_local}}",
        "value_type": "liquid"
      },
      {
        "key": "custom",
        "value": "custom_method",
        "value_type": "plain"
      }
    ]
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"}
      ],
      "combine_op": "and"
    }
  }
}

{
  "name": "apicast.policy.logging",
  "configuration": {
    "enable_access_logs": false,
    "custom_logging": "\"{{request}}\" to service {{service.id}} and {{service.name}}",
    "condition": {
      "operations": [
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "200"},
        {"op": "==", "match": "{{status}}", "match_type": "liquid", "value": "500"}
      ],
      "combine_op": "or"
    }
  }
}

Maintenance Mode 策略允许您使用指定状态代码和消息拒绝传入的请求。它对于维护期或临时阻止 API 非常有用。

配置属性

下表列出了可能的属性和默认值：

{
  "policy_chain": [
    {"name": "maintenance-mode", "version": "1.0.0",
    "configuration": {"message": "Be back soon..", "status": 503} },
  ]
}

{
    "name": "maintenance_mode",
    "version": "builtin",
    "configuration": {
        "message_content_type": "text/plain; charset=utf-8",
        "message": "Echo API /test is currently Unavailable",
        "condition": {
            "combine_op": "and",
            "operations": [
                {
                    "left_type": "liquid",
                    "right_type": "plain",
                    "op": "==",
                    "left": "{{ original_request.path }}",
                    "right": "/test"
                }
            ]
        },
        "status": 503
    }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

NGINX 会自动检查某些请求标头并在无法验证这些标头时拒绝请求。例如，NGINX 拒绝具有 NGINX 无法验证的 If-Match 标头的请求。如果您希望 NGINX 跳过特定标头的验证，请添加 NGINX Filter 策略。

添加 NGINX Filter 策略时，您要为需要 NGINX 跳过验证指定一个或多个请求标头。对于您指定的每个标头，您可以指定是否在请求中保留标头。例如，以下 JSON 代码添加 NGINX 过滤器策略，以便它跳过 if-Match 标头的验证，但在转发到上游服务器的请求中保留 If-Match 标头。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": true}
    ]
  }
}

下一个示例还跳过了 If-Match 标头的验证，但此代码指示 NGINX 在向上游服务器发送请求前删除 If-Match 标头。

{ "name": "apicast.policy.nginx_filters",
  "configuration": {
    "headers": [
      {"name": "If-Match", "append": false}
    ]
  }
}

无论您是否将指定的标头附加到上游服务器的请求中，当 NGINX 无法验证您指定的标头时，您避免了 NGINX 412 响应代码。

此策略为每个 API 调用执行 OAuth 2.0 通用 TLS 客户端身份验证。

OAuth 2.0 通用 TLS 客户端身份验证策略 JSON 示例如下所示：

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "OAuth 2.0 Mutual TLS Client Authentication",
  "summary": "Configure OAuth 2.0 Mutual TLS Client Authentication.",
  "description": ["This policy executes OAuth 2.0 Mutual TLS Client Authentication ",
    "(https://tools.ietf.org/html/draft-ietf-oauth-mtls-12) for every API call."
  ],
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": { }
  }
}

OAuth 2.0 Token Introspection 策略允许使用令牌签发者(Red Hat Single Sign-On)的 Token Introtion Endpoint(Red Hat Single Sign-On)验证选项来验证用于通过 OpenID Connect(OIDC)身份验证选项的 JSON Web Token Token 令牌(JWT)令牌。

APIcast 支持 auth_type 字段中的以下身份验证类型，以确定 Token Introspection Endpoint 和调用此端点时使用的凭证 APIcast：

无论 auth_type 字段中的设置是什么，APIcast 使用 Basic Authentication 来授权 Token Introspection 调用（Authorization：Basic <token> header, where <token> is Base64-encoded <client_id>:<client_secret> setting).

Token Introspection Endpoint 的响应中包含 active 属性。APIcast 检查此属性的值。根据属性的值，APIcast 授权或拒绝调用：

该策略允许缓存令牌，以避免在相同 JWT 令牌的每个调用中调用 Token Introspection Endpoint。要为 Token Introspection Policy 启用令牌缓存，请将 max_cached_tokens 字段设置为从 0 （禁用该功能）到 10000 直接的值。另外，您可以在 max_ttl_tokens 字段中将令牌的值从 1 设置为 3600 秒。

作为 API 供应商，您可以将 On Fail 策略添加到 API 产品中。当 On Fail 策略位于策略链中，并且针对给定的 API 使用者请求执行策略会失败，APIcast 执行以下操作：

当 APIcast 无法处理策略时，On Fail 策略很有用，这可能是因为配置不正确，或因为自定义策略中不合规的代码。如果没有策略链中的 On Fail 策略，APIcast 会跳过它无法应用的策略，在链中处理任何其他策略，并将请求发送到上游 API。在策略链中使用 On Fail 策略，APIcast 拒绝请求。

在策略链中，On Fail 策略可以处于任何位置。

在管理门户中，将 On Fail 策略添加到产品的策略链中。在策略链中，点击策略指定您希望 APIcast 在应用 On Fail 策略时返回的状态代码。例如，您可以指定 400，这表示来自客户端的错误请求。

您可以使用 Proxy Service 策略定义一个通用 HTTP 代理，该代理将使用定义的代理发送 3scale 流量。在这种情况下，代理服务充当反向 HTTP 代理，APIcast 将流量发送到 HTTP 代理，代理随后将流量发送到 API 后端。

以下示例显示了流量流：

发送到 3scale 后端的所有 APIcast 流量都不使用代理。此策略只适用于代理以及 APIcast 和 API 后端之间的通信。

如果要通过代理发送所有流量，则必须使用 HTTP_PROXY 环境变量。

"policy_chain": [
    {
      "name": "apicast.policy.apicast"
    },
    {
      "name": "apicast.policy.http_proxy",
      "configuration": {
          "all_proxy": "http://192.168.15.103:8888/",
          "https_proxy": "https://192.168.15.103:8888/",
          "http_proxy": "https://192.168.15.103:8888/"
      }
    }
]

如果未定义 http_proxy 或 https_proxy，则使用 all_proxy 值。

当应用程序订阅具有速率限制的应用程序计划时，Rate Limit Headers 策略会添加 RateLimit 标头来响应消息。这些标头提供有关当前时间窗口中配置的请求配额和剩余的请求配额和秒的有用信息。

在产品的策略链中，如果您添加 Rate Limit Headers 策略，则必须在 3scale APIcast 策略之前。如果 3scale APIcast 策略早于 Rate Limit Headers 策略，则 Rate Limit Headers 策略不起作用。

默认情况下，当没有配置 Rate Limit Headers 策略或应用程序计划没有任何速率限值限制时，响应消息中没有速率限制标头。

作为 API 提供程序，您可以将 Response/Request Content Limits 策略添加到 API 产品。此策略允许您将请求的大小限制为上游 API，以及来自上游 API 的响应大小。如果没有此策略，请求/响应大小将无限制。

此策略有助于防止过载：

在请求或响应中，3scale 需要 content-length 标头来应用 Response/Request Content Limits 策略。

在管理门户中，在将 Response/Request Content Limits 策略添加到产品后，单击它以字节为单位指定限值。您可以指定请求限值或响应限值，或同时指定两者。默认值为 0，表示无限大小。

另外，您可以通过更新策略链配置文件来添加此策略，例如：

{
  "name": "apicast.policy.limits",
  "configuration":
  {
    "request": 100,
    "response": 100
  }
}

重试策略将请求数设置为上游 API。重试策略是为每个服务配置的，因此用户可以根据需要为任意数量或任意数量的服务启用重试，并为不同的服务配置不同的重试值。

重试策略 JSON 的示例如下所示：

{
  "$schema": "http://apicast.io/policy-v1/schema#manifest#",
  "name": "Retry",
  "summary": "Allows retry requests to the upstream",
  "description": "Allows retry requests to the upstream",
  "version": "builtin",
  "configuration": {
    "type": "object",
    "properties": {
      "retries": {
        "description": "Number of retries",
        "type": "integer",
        "minimum": 1,
        "maximum": 10
      }
    }
  }
}

此策略在与 OpenID Connect 身份验证选项一起使用时添加角色检查。此策略验证红帽单点登录(RH-SSO)中发布的访问令牌中的域角色和客户端角色。当您要向 3scale 的每个客户端资源添加角色检查时，会指定 realm 角色。

有两种类型的角色检查策略配置中指定的 type 属性：

同一策略中无法同时配置 blacklist 和 whitelist 检查，但您可以在 APIcast 策略链中添加多个 RH-SSO/Keycloak 角色检查 策略链。

您可以通过策略配置的 scopes 属性配置范围列表。

每个 scope 对象具有以下属性：

Routing 策略允许您将请求路由到不同的目标端点。您可以定义目标端点，然后将从 UI 传入的请求路由到使用正则表达式的请求。

Liquid Context Debug
JWT Claim Check
Routing
3scale APIcast

Liquid Context Debug
Routing
3scale APIcast
JWT Claim Check

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "query_arg",
                "query_arg_name": "test_query_arg",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是当 JWT 声明 test_claim 的值为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "jwt_claim",
                "jwt_claim_name": "test_claim",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是在请求的路径为 /accounts 以及标头 Test-Header 的值为 123 时路由到 http://example.com 的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "and",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是在请求的路径为 /accounts 或者标头 Test-Header 的值为 123 时路由到 http://example.com 的配置 ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "combine_op": "or",
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              },
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "123"
              }
            ]
          }
        }
      ]
    }
  }

这是包含多个规则的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/accounts"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/users"
              }
            ]
          }
        }
      ]
    }
  }

如果路径为 /abc，则此配置将请求路由到 http://some_upstream.com，如果路径是 /def，将请求路由到 http://another_upstream.com，最后，如果之前的规则没有评估为 true，则会将请求路由到 http://default_upstream.com ：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://some_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/abc"
              }
            ]
          }
        },
        {
          "url": "http://another_upstream.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/def"
              }
            ]
          }
        },
        {
          "url": "http://default_upstream.com",
          "condition": {
            "operations": []
          }
        }
      ]
    }
  }

这是使用 != 的配置。当路径不是 /accounts 时，它会路由到 http://example.com:

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "!=",
                "value": "/accounts"
              }
            ]
          }
        }
      ]
    }
  }

这是使用该值路由请求的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "condition": {
            "operations": [
              {
                "match": "header",
                "header_name": "Test-Header",
                "op": "==",
                "value": "{{ my_var }}",
                "value_type": "liquid"
              }
            ]
          }
        }
      ]
    }
  }

这是将 some_host.com 指定为 Host 标头主机的配置：

 {
    "name": "routing",
    "version": "builtin",
    "configuration": {
      "rules": [
        {
          "url": "http://example.com",
          "host_header": "some_host.com",
          "condition": {
            "operations": [
              {
                "match": "path",
                "op": "==",
                "value": "/"
              }
            ]
          }
        }
      ]
    }
  }

SOAP 策略与 HTTP 请求的 SOAPAction 或 Content-Type 标头中提供的 SOAP 操作 URI 匹配策略中指定的映射规则。

配置属性

策略对象示例

{
  "name": "soap",
  "version": "builtin",
  "configuration": {
    "mapping_rules": [
      {
        "pattern": "http://example.com/soap#request",
        "metric_system_name": "soap",
        "delta": 1
      }
    ]
  }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

借助 TLS 客户端证书验证策略，APIcast 实施 TLS 握手，并根据白名单验证客户端证书。白名单包含由认证机构(CA)或纯客户端证书签名的证书。如果证书过期或无效，请求将被拒绝，且不会处理其他策略。

客户端连接到 APIcast 以发送请求并提供客户端证书。APIcast 根据策略配置验证传入请求中提供的证书的真实性。APIcast 也可以配置为使用自己的客户端证书，以在连接到上游时使用它。

您必须有权访问 3scale 安装。您必须等待所有部署完成。

另外：

要保存您的更改，请点击 Update Policy Chain。

您可以通过在占位符中指定 [Your_user_key] 来验证应用的策略。

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key

curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt

要保存您的更改，请点击 Update Policy Chain。

有关使用证书的更多信息，请参阅 红帽认证系统。

本节提供有关传输层安全(TLS)终止策略的信息：从策略中移除概念、配置、验证和文件删除。

借助 TLS Termination 策略，您可以将 APIcast 配置为为每个 API 完成 TLS 请求，而无需为所有 API 使用单个证书。APIcast 在建立与客户端的连接前拉取配置设置；因此，APIcast 使用策略中的证书，并使 TLS 终止。此策略可与以下源配合工作：

默认情况下，策略链中不启用此策略。

按照以下步骤操作：

另外：

要保存您的更改，请点击 Update Policy Chain。

如果策略可使用以下命令，则可以在命令行中测试：

curl “${public_URL}:${port}/?user_key=${user_key}" --cacert ${path_to_certificate}/ca.pem -v

其中：

删除证书：

要保存您的更改，请点击 Update Policy Chain。

通过 Upstream 策略，您可以使用正则表达式来解析主机请求标头，并将私有基本 URL 中定义的上游 URL 替换为不同的 URL。

例如：

具有 regex /foo 的策略和 URL 字段 newexample.com 将 URL https://www.example.com/foo/123/ 替换为 newexample.com

策略链参考：

策略对象示例

{
  "name": "upstream",
  "version": "builtin",
  "configuration": {
    "rules": [
      {
        "regex": "^/v1/.*",
        "url": "https://api-v1.example.com",

      }
    ]
  }
}

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

Upstream Connection 策略允许您为每个 API 更改以下指令的默认值，具体取决于您在 3scale 安装中配置 API 后端服务器的方式：

配置上游连接策略：

按照以下步骤操作：

要保存您的更改，请点击 Update Policy Chain。

使用 Upstream Mutual TLS 策略，您可以根据配置中设置的证书在 APIcast 和上游 API 之间建立并验证 mutual TLS 连接。

启用 verify 字段后，策略还会验证来自上游 API 的服务器证书。ca_certificates 包含 Privacy Enhanced Mail(PEM)格式的证书，包括 -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- APIcast 使用它来验证服务器。

要在策略链中配置上游双向 TLS，您需要有权访问 3scale 安装。

推进您的更改：

V# 代表要提升的配置的版本号。

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
      "certificate": "/secrets/client.cer",
      "certificate_type": "path",
      "certificate_key": "/secrets/client.key",
      "certificate_key_type": "path"
  }
}

{
  "name": "apicast.policy.upstream_mtls",
  "configuration": {
    "certificate_type": "embedded",
    "certificate_key_type": "embedded",
    "certificate": "data:application/pkix-cert;name=client.cer;base64,XXXXXXXXXXX",
    "certificate_key": "data:application/x-iwork-keynote-sffkey;name=client.key;base64,XXXXXXXX"
  }
}

有关 Upstream Mutual TLS 的其他字段 ca_certificates 和 verify，策略配置模式 的详细。

URL 重写策略允许您修改请求的路径和查询字符串。

与 3scale APIcast 策略结合使用时，如果在策略链中的 APIcast 策略之前放置 URL 重写策略，APIcast 映射规则将应用到修改的路径。如果在 APIcast 链中的 APIcast 后放置了 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

应用以下转换：

有关如何配置策略的详情，请参考文档中 3scale 中的创建策略链 部分。

URL 重写策略是 URL 重写策略的替代选择，允许在将 API 请求传递给 API 后端前重写 API 请求的 URL。

URL 使用 Captures 策略检索 URL 中的参数，并在重写 URL 中使用其值。

该策略支持 transformations 配置参数。这是一个对象列表，用于描述将哪些转换应用到请求 URL。每个调整对象由两个属性组成：

原始 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

Websocket 策略启用 WebSocket 协议连接到上游 API。如果您计划启用 WebSocket 协议，请考虑以下几点：

对于启用了 WebSocket 连接的给定上游 API，您可以将其后端定义为 http[s] 或 ws[s]。

如果您在策略链中添加了 Websocket 策略，请确保 Websocket 策略在 3scale APIcast 策略之前。