映射规则在 API 产品和 API 后端级别上工作。在本节中，您将了解每个级别的映射规则的行为，并查看一个示例来描述映射规则如何运作。

/hello
/bye

/echo/hello
/echo/bye

现在，请考虑使用同一 Echo API 后端的名为 Tools for Devs 的额外产品。

映射规则的匹配由前缀执行，可以是任意复杂的。符号遵循 OpenAPI 和 ActiveDocs 规格：

映射规则有以下工作流：

(get) /path/to/example/search
(get) /path/to/example/{id}

在使用 (get)/path/to/example/search 调用时，APIcast 会停止处理剩余的映射规则，并在规则匹配后递增其指标。

要在 APIcast 部署中添加分布式追踪，您需要确保以下先决条件：

要配置 OpenTracing，请使用以下环境变量：

有关这些变量的更多信息，请参阅 APIcast 环境变量。

要测试集成是否正常工作，您需要检查 Jaeger 追踪界面中是否报告 trace。

OpenTracing 和 Jaeger 集成在上游项目中找到 ：https://github.com/3scale/apicast

本节提供有关在运行的 OpenShift 实例上安装 Jaeger 的信息。

有关配置 Jaeger 的更多信息，请参阅：

docker：无法连接到 Docker 守护进程。Is the docker daemon running on this host? 错误消息可能是 Docker 服务尚未启动。您可以通过运行 sudo systemctl status docker.service 命令来检查 Docker 守护进程的状态。

确保您以 root 用户身份运行此命令，因为 Docker 容器化环境默认需要在 RHEL 中具有 root 权限。有关详细信息，请参阅 此处。

如果您以分离模式启动容器（-d 选项），并希望检查正在运行的 APIcast 实例的日志，您可以使用 log 命令： sudo docker logs <container>。其中，<container> 是容器名称（上例中的 "apicast"）或容器 ID。您可以使用 sudo docker ps 命令获取正在运行的容器及其 ID 和名称的列表。

要停止容器，请运行 sudo docker stop <container> 命令。您还可以运行 sudo docker rm <container> 命令删除容器。

有关可用命令的更多信息，请参阅 Docker 命令参考。

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. 匿名访问策略

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

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

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

                             |
                             v

                          Headers

                             |
                             v

                       URL Rewriting

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

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

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

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

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

通过允许您指定以下指定来控制 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"
  }
}

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

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

配置属性

策略对象示例

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

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

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

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

"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 中的创建策略链 部分。

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)声明，您可以通过定义新规则来阻止资源目标和方法。

{
  "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 参数的详情，请参考 ???。

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

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.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} },
  ]
}

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

此策略为每个 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：

"policy_chain": [
…​
  {
    "name": "apicast.policy.token_introspection",
    "configuration": {
      "auth_type": "use_3scale_oidc_issuer_endpoint"
    }
  }
…​
],

"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 &gt ; 是 Base64 编码的 < client_id>:<client_secret&gt;）。

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

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

Proxy Service 策略允许用户定义 通过定义的代理发送流量的 HTTP 代理。

以下显示了流量流示例：

                 ,-------.          ,---------.          ,----------.
                 |APIcast|          |HTTPPROXY|          |APIBackend|
  User           `---+---'          `----+----'          `----------'
   |  GET /resource  |                   |                    |
   | --------------->|                   |                    |
   |                 |                   |                    |
   |                 |  Get /resource    |                    |
   |                 |------------------>|                    |
   |                 |                   |                    |
   |                 |                   |  Get /resource/    |
   |                 |                   | - - - - - - - - - >|
   |                 |                   |                    |
   |                 |                   |     response       |
   |                 |                   |<- - - - - - - - - -|
   |                 |                   |                    |
   |                 |     response      |                    |
   |                 |<------------------|                    |
   |                 |                   |                    |
   |                 |                   |                    |
   | <---------------|                   |                    |
  User           ,---+---.          ,----+----.          ,----------.
                 |APIcast|          |HTTPPROXY|          |APIBackend|
                 `-------'          `---------'          `----------'

到 3scale 后端的所有 APIcast 流量都不会使用代理，因此这只适用于该服务和 APIcast 和 API 后端之间的通信。

如果要通过 Proxy Service 策略使用所有流量，则必须使用 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/"
      }
    }
]

重试策略将请求数设置为上游 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 传入的请求路由到使用正则表达式的请求。

与 APIcast 策略组合时，路由策略应放在链中的 APIcast 之前，因为首先将内容输出到响应的两个策略。当第二个进程获得更改以运行其内容阶段时，该请求已发送到客户端，因此不会输出到响应。

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

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

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

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

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

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

 {
    "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 也可以配置为使用自己的客户端证书，以在连接到上游时使用它。

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

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

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

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

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

通过 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 中的创建策略链 部分。

根据您在 3scale 安装中配置 API 后端服务器的方式，为每个 API 更改以下指令的默认值：

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

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

https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original

https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue

使用 Captures 策略的 URL Rewriting 是 第 4.1.27 节 “URL Rewriting” 策略的替代，并允许在将 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

如果创建了自定义策略，则必须将它们添加到 APIcast 中。具体方法取决于 APIcast 部署的位置：

要将自定义 APIcast 策略添加到内部部署中，您必须构建包含自定义策略的 OpenShift 镜像，并将其添加到您的部署中。3scale 提供了一个示例存储库，您可以使用作为框架来创建和添加自定义策略到内部部署。

此示例存储库包含自定义策略的正确目录结构，以及用于创建镜像流和 BuildConfig 的模板，用于构建包含您创建的任何自定义策略的新 APIcast OpenShift 镜像。

在内部部署中添加自定义策略：

如果内置 APIcast 镜像跟踪 amp-apicast:latest 镜像流中的更改，则 APIcast 的新部署将启动。apicast-staging 重启后，导航到 Integration > Policies，然后点击 Add Policy 按钮来查看列出的自定义策略。选择并配置后，单击 Update Policy Chain，使自定义策略在暂存 APIcast 中正常工作。

您可以通过从集成的 OpenShift Container Platform 注册表获取包含自定义策略的镜像，将自定义策略添加到 OpenShift Container Platform (OCP)上的 APIcast。

在另一个 OpenShift Container Platform 上将自定义策略添加到 APIcast 中

在 Prometheus UI 中，您可以使用 Prometheus Query Language(PromQL)编写查询来提取指标信息。使用 PromQL，您可以实时选择和聚合时间序列数据。

例如，您可以使用以下查询为指标名称 http_requests_total 选择 Prometheus 在最后 5 分钟内记录的所有值：

http_requests_total[5m]

您可以通过为指标指定 label （键：值对）来进一步定义或过滤查询的结果。例如，您可以查询以下查询，为指标名称 http_requests_total 和 job 标签设置为 integration 的所有时间序列选择 Prometheus 在最后 5 分钟内记录的所有值：

http_requests_total{job="integration"}[5m]

查询的结果可以显示为一个图形，在 Prometheus 的表达式浏览器中作为表格数据查看，或者通过使用 Prometheus HTTP API 由外部系统使用。Prometheus 提供数据的图形视图。要获得更强大的图形仪表板来查看 Prometheus 指标，Grafana 是一种常见选择。

您还可以使用 PromQL 语言在 Prometheus alertmanager 工具中配置警报。

另外，如果您有集群管理员对 OpenShift 集群的访问权限，您可以扩展 total_response_time_seconds, upstream_response_time_seconds, and upstream_status metrics to include service_id 和 service_system_name 标签。要扩展这些指标，使用以下命令将 APICAST_EXTENDED_METRICS OpenShift 环境变量设置为 true ：

oc set env dc/apicast APICAST_EXTENDED_METRICS=true

如果您使用 APIcast Batch 策略（描述在 第 4.1.2 节 “3scale Batcher”中），Prometheus 也可以监控 表 9.3 “3scale APIcast 批处理策略的 Prometheus Metrics” 中列出的指标。

导航到您要处理的 API 服务（在这种情况下，可能只有一个名为 API 的服务）。前往 Integration 部分。

您运行的每个服务都可以使用不同的身份验证模式，但每个服务只能使用一种模式。

若要选择身份验证模式，可滚动到 AUTHENTICATION 部分。在这里，您可以选择以下选项之一：

根据所选的凭证类型，您可能需要接受 API 调用中的不同参数（密钥字段、ID 等）。这些参数的名称可能与 3scale 中内部使用的参数不同。如果在 3scale 后端调用中使用了正确的参数名称，3scale 身份验证将正确运行。

为确保凭据集正常工作，您可以创建一个新应用来签发凭据以使用 API。导航到管理门户控制面板的 Accounts 区域，单击要使用的帐户，再单击 新应用程序。

填写表单并单击 save 将创建一个包含凭据的新应用，以使用 API。现在，您可以使用这些凭证来调用 API，并且会根据 3scale 中注册的应用程序列表检查记录。

支持最简单的凭证形式是单一 API 模型。在这里，每个具有 API 权限的应用程序都有单个（唯一）长字符串；例如：

API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13

默认情况下，key 参数的名称是 user_key。您可以使用该标签或选择另一个标签，如 API-key。如果选择其他标签，则需要在向 3scale 发出授权调用前映射该值。字符串同时充当标识符和机密令牌，供 API 使用。建议您仅在安全要求低或 API 调用的 SSL 安全性的环境中使用这些模式。以下是可以在令牌和应用程序上执行的操作：

后一操作可以从管理门户中的 API 管理以及（如果允许）从 API Developers 用户控制台触发。

API Key Pattern 将应用程序的身份和 secret 用量令牌组合在一个令牌中，但这种模式将两者分开：

app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4

在默认设置中，开发人员可以为每个应用创建最多五个密钥。这允许开发人员创建新密钥，将它添加到代码中，重新部署其应用，然后禁用旧密钥。这不会以 API 密钥重新生成的方式造成应用程序停机。

统计信息和速率限值始终保持在应用程序 ID 的粒度级别，而不是每个 API 密钥。如果开发人员希望跟踪两组统计数据，他们应创建两个应用，而不是两个键。

也可以更改系统上的模式，并允许在没有应用密钥的情况下创建应用程序。在这种情况下，3scale 系统将仅根据 App ID 验证访问权限（不进行密钥检查）。此模式可用于小部件类型场景，或者对用户而非应用程序应用速率限制。在大多数情况下，您可能希望 API 强制每个应用程序存在至少一个应用程序密钥。此设置包括在 [your_API_name] > Integration > Settings 中。

有关 OpenID Connect 身份验证的详情，请查看 OpenID Connect 集成 章节。

要配置 RH-SSO，请执行以下步骤：

在 RH-SSO 中创建并配置了客户端后，您必须配置 3scale 以使用 RH-SSO。

要配置 3scale，请执行以下步骤：

要配置 OIDC 与第三方身份提供程序的 HTTP 集成，请在管理门户中按照以下步骤执行：

这个示例项目实施 Zync REST API 协议来同步 OAuth2.0 客户端。在创建 3scale 应用程序时，更新或删除 Zync 会尝试将该更改复制到 http://example.com/api。

{
  "client_id": "ee305610",
  "client_secret": "ac0e42db426b4377096c6590e2b06aed",
  "client_name": "oidc-app",
  "redirect_uris": ["http://example.com"],
  "grant_types": ["client_credentials", "password"]
}

{
  "token_endpoint": "http://idp.example.com/auth/realm/token"
}

客户端使用授权请求或令牌请求获取访问令牌，或两者。接收这些请求的 URL 可以在相应 "authorization_endpoint" 和 "token_endpoint" 的 OpenID 提供程序的 .well-known/openid-configuration 端点中发现。示例： https://<RHSSO_HOST>:<RHSSO_PORT>/auth/realms/<REALM_NAME>/.well-known/openid-configuration.

您可以在管理门户中为 3scale API 配置允许的 OAuth 2.0 流。当您创建新应用程序时，基本集成已完成，包括 OpenId Connect(OIDC)配置。

要配置 OAuth 2.0 支持的流，请执行以下步骤：

要测试客户端同步，请执行以下步骤：

要测试 APT 授权流，请执行以下步骤：

如果令牌正确并且 3scale 中的对应应用程序被授权，APIcast 网关会返回来自 3scale 后端的响应。