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

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

映射规则

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

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

Hello World 映射规则

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

  • 在产品级别上映射规则。

    • 映射规则具有优先权。这意味着产品映射规则是第一个要评估的规则。
    • 映射规则始终被评估，并且独立于这些后端接收重定向的流量。

  • 在后端级别映射规则。

    • 当您向后端添加映射规则时，这些规则将添加到所有产品中，并绑定所述后端。
    • 映射规则在产品级别上定义的映射规则后评估。
    • 只有在流量重定向到映射规则所属的同一后端时才评估映射规则。
    • 产品后端的路径会自动放在捆绑到上述产品的后端的每个映射规则的前面。

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

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

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

映射规则的匹配

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 状态代码丢弃该请求。

映射规则工作流

映射规则有以下工作流：

  • 您可以随时定义一个新的映射规则。请参阅 定义映射规则。
  • 下一次重新加载时将灰显映射规则，以防止意外修改。
  • 要编辑现有的映射规则，您必须首先通过单击右侧的铅笔图标启用它。
  • 若要删除规则，可单击回收站图标。
  • 当您提升 Integration > Configuration 中的更改时，所有修改和删除都会保存。

停止其他映射规则

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

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

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