1.2. APIcast 如何应用映射规则来捕获 3scale API 的使用

根据对 API 的请求，映射规则定义指标或指定您要捕获 API 使用情况的方法。以下是映射规则的示例：

此规则意味着，任何以 / 开头的 GET 请求都以 1 为指标 hits 的增量。此规则匹配到您的 API 的任何请求。虽然这是有效的映射规则，但它太通用，如果您添加了更具体的映射规则，则通常会导致被双倍计数。

Echo API 的以下映射规则显示更为具体的示例：

映射规则在 API 产品和 API 后端级别上工作。

在产品级别上映射规则。
- 映射规则具有优先权。这意味着产品映射规则是第一个要评估的规则。
- 映射规则始终被评估，并且独立于这些后端接收重定向的流量。
在后端级别映射规则。
- 当您向后端添加映射规则时，这些规则将添加到所有产品中，并绑定所述后端。
- 映射规则在产品级别上定义的映射规则后评估。
- 只有在流量重定向到映射规则所属的同一后端时才评估映射规则。
- 产品后端的路径会自动放在捆绑到上述产品的后端的每个映射规则的前面。

使用产品和后端映射规则示例

以下示例显示了一个后端产品的映射规则。

Echo API 后端：
- 具有专用端点：https://echo-api.3scale.net
- 包含使用以下模式的 2 个映射规则：
```
/hello
/bye
```
Cool API 产品：
- 具有这个公共端点：https://cool.api
- 通过以下路由路径使用 Echo API 后端： /echo。
使用以下模式映射规则会自动成为 Cool API 产品的一部分：
```
/echo/hello
/echo/bye
```
- 这意味着发送到公共 URL https://cool.api/echo/hello 的请求被重新定向到 https://echo-api.3scale.net/hello。
- 同样，发送到 https://cool.api/echo/bye 的请求重定向至 https://echo-api.3scale.net/bye。

现在，假设有一个名为 Tools For Devs 的其他产品，它使用相同的 Echo API 后端。

Tools for Devs 产品：
- 具有这个公共端点：https://dev-tools.api
- 通过以下路由路径使用 Echo API 后端： /tellmeback。
使用以下模式映射规则是 Tools For Devs 产品的一部分：
```
/tellmeback/hello
/tellmeback/bye
```
- 因此，发送到公共 URL https://dev-tools.api/tellmeback/hello 的请求会被重定向到 https://echo-api.3scale.net/hello。
- 同样，发送到 https://dev-tools.api/tellmeback/bye 的请求重定向至 https://echo-api.3scale.net/bye。
如果您使用 /ping 模式的映射规则添加到 Echo API 后端，则产品 - Cool API 和 Tools For Devs 都会受到影响：
- cool API 具有一个使用此模式的映射规则： /echo/ping。
- Tools For Devs 有具有此模式的映射规则： /tellmeback/ping。

映射规则的匹配

3scale 根据前缀应用映射规则。表示法遵循 OpenAPI 和 ActiveDocs 规格：

映射规则必须以正斜杠(/)开头。
在路径上对文字字符串执行匹配，即 URL，例如 /hello。
- 映射规则保存后，将导致请求发送到您已设置的 URL 字符串，并调用您围绕每个映射规则定义的指标或方法。
映射规则可以在查询字符串或正文中包含参数，例如 /{word}?value={value}。
APIcast 获取参数的方式如下：
- GET 方法：来自查询字符串。
- POST、DELETE 或 PUT 方法：从正文。
映射规则可以包含命名通配符，例如 /{word}。此规则与占位符 {word} 中的任何内容匹配，它会使 /morning 等请求与映射规则匹配。通配符可以在斜杠之间或斜杠和点之间出现。参数也可以包含通配符。
默认情况下，所有映射规则都会根据您指定的排序顺序从第一到最后一个评估。如果您添加规则 /v1，它将匹配路径以 /v1 开头的请求，例如： /v1/word 或 /v1/sentence。
您可以在模式的末尾添加一个美元符号($)来指定完全匹配项。例如，/v1/word 仅匹配 /v1/word 请求，不匹配 /v1/word/hello 请求。要完全匹配，还必须确保禁用了与所有(/)匹配的默认映射规则。
多个映射规则可以匹配请求路径，但如果都不匹配，则会使用 HTTP 404 状态代码丢弃该请求。

映射规则工作流

映射规则有以下工作流：

停止其他映射规则

在处理一个或多个映射规则后，若要停止处理其他映射规则，请在创建新的映射规则时选择 Last?。例如，假设 API 集成设置 中定义了以下映射规则，并且每个规则都有不同的指标：

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

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