使用插件

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

Edge Microgate v. 3.3.x

受众群体

本主题适用于希望使用随微网关安装的现有插件的 Edge Microgate 运维人员。此外，还详细讨论了高峰控制插件和配额插件（两者都包含在安装中）。如果您是开发者，希望开发新插件，请参阅开发自定义插件。

什么是 Edge Microgate 插件？

插件是一个向 Edge Microgate 添加功能的 Node.js 模块。插件模块遵循一致的模式，并存储在 Edge Microgate 已知的位置，因此微网关能够自动发现和加载这些模块。Edge Microgate 包含几个现有插件，您还可以创建自定义插件，如开发自定义插件中所述。

与 Edge Microgate 捆绑的现有插件

Edge Microgate 在安装时提供了许多插件。下表介绍了一些最常用的插件。

插件 默认处于启用状态 说明
分析 是 将分析数据从 Edge Microgate 发送到 Apigee Edge。
oauth 是 向 Edge Microgate 添加了 OAuth 令牌和 API 密钥验证功能。请参阅设置和配置 Edge Microgate。
配额 否 对发送到 Edge Microgate 的请求强制执行配额。使用 Apigee Edge 存储和管理配额。请参阅使用配额插件。
Sspikearrest 否 可防范流量高峰和 DoS 攻击。请参阅使用高峰控制插件。
标头-大写 否 带注释的示例代理，可作为指导，帮助开发者编写自定义插件。 请参阅 Edge Microgate 示例插件。
accumulate-request 否 先将请求数据累积到单个对象中，然后再将数据传递给插件链中的下一个处理程序。在编写需要对单个累积的请求内容对象执行操作的转换插件时，比较实用。
累积响应 否 先将响应数据累计到单个对象中，然后再将该数据传递给插件链中的下一个处理程序。在编写需要对单个累积的响应内容对象执行操作的转换插件时，比较实用。
transform-uppercase 否 转换请求或响应数据。该插件代表了转换插件的最佳实践实现方式。示例插件会执行一项无关紧要的转换（将请求或响应数据转换为大写）；不过，它可以轻松地进行调整以执行其他类型的转换，例如从 XML 到 JSON。
json2xm 否 根据接受或内容类型标头转换请求或响应数据。如需了解详情，请参阅 GitHub 中的插件文档。
quota-memory 否 对发送到 Edge Microgate 的请求强制执行配额。在本地内存中存储和管理配额。
healthcheck 否 返回有关 Edge Microgate 进程的信息（内存用量、CPU 用量等）。如需使用该插件，请在您的 Edge Microgate 实例上调用网址 /healthcheck。此插件是一个示例，可供您用来实现自己的健康检查插件。

在哪里可以找到现有插件

与 Edge Microgate 捆绑的现有插件都位于此处，其中 [prefix] 是 npm 前缀目录。如果您找不到此目录，请参阅 Edge Microgate 的安装位置。

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

添加和配置插件

请按照以下格式添加和配置插件：

  1. 停止 Edge Microgate。
  2. 打开 Edge Microgate 配置文件。如需了解详情，请参阅 更改配置以了解相关选项。
  3. 将该插件添加到配置文件的 plugins:sequence 元素中，如下所示。 插件会按照此列表中显示的顺序执行。
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. 配置插件。某些插件具有可选参数，您可以在配置文件中配置这些参数。例如，您可以添加以下节来配置高峰控制插件。如需了解详情，请参阅使用高峰控制插件。 
    edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
  1. 保存文件。
  2. 重启或重新加载 Edge Microgate，具体取决于您所修改的配置文件。

插件专用配置

您可以通过在此目录中创建插件专用配置来替换配置文件中指定的插件参数：

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

其中，[prefix] 是 npm 前缀目录。如果您找不到此目录，请参阅 Edge Microgate 的安装位置。

plugins/<plugin_name>/config/default.yaml。例如，您可以将此块放在 plugins/spikearrest/config/default.yaml 中，它们将替换任何其他配置设置。

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

使用高峰控制插件

高峰控制插件可防范流量高峰。它限制了 Edge Microgate 实例处理的请求数。

添加高峰控制插件

请参阅添加和配置插件。

高峰控制的示例配置

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

高峰控制的配置选项

  • timeUnit：高峰控制执行时段重置的频率。有效值为秒或分钟。
  • allow：timeUnit 期间允许的请求数量上限。另请参阅如果您正在运行多个 Edge Micro 进程。
  • bufferSize：（可选，默认值 = 0）如果 bufferSize > 0，则高峰控制会将此数量的请求存储在缓冲区中。当下一个执行“窗口”发生时，系统会首先处理缓冲的请求。另请参阅添加缓冲区。

高峰控制是如何运作的？

将高峰控制视为一种通常防范流量高峰的方法，而不是将流量限制为特定数量的请求。您的 API 和后端可以处理一定数量的流量，而高峰控制政策可帮助您将流量平稳到您想要的常规数量。

运行时高峰控制行为可能与您输入的每分钟或每秒字面量值可能有所不同。

例如，假设您指定的速率为每分钟 30 个请求，如下所示：

spikearrest:
   timeUnit: minute
   allow: 30

在测试中，您可能认为自己可以在 1 秒内发送 30 个请求，只要这些请求在一分钟内发出即可。但此政策并不是强制执行该设置的方式。您可以想一想，在某些环境中，1 秒内的 30 个请求可被视为微小峰值。

那么，然后会怎么样呢？为了防止出现类似高峰的行为，高峰控制通过将设置划分为更小的时间间隔来平滑允许的流量，如下所示：

每分钟费率

每分钟速率会平滑处理为允许的秒数间隔。例如，每分钟 30 个请求会经过平滑处理，如下所示：

60 秒（1 分钟）/30 = 2 秒间隔，即大约每 2 秒允许 1 个请求。在 2 秒之内的第二个请求将失败。此外，一分钟内的第 31 个请求将失败。

每秒速率

每秒速率会平滑处理为允许时间间隔（以毫秒为单位）的请求。例如，每秒 10 个请求会变得平滑处理，如下所示：

间隔为 1000 毫秒（1 秒）/10 = 100 毫秒，或者每 100 毫秒大约允许 1 个请求。100 毫秒内发出的第二个请求将会失败。此外，一秒内的第 11 个请求也将失败。

超出上限时

如果请求数超过指定时间间隔内的上限，高峰控制事件将返回以下错误消息并指明 HTTP 503 状态：

{"error": "spike arrest policy violated"}

添加缓冲区

您可以选择为政策添加缓冲区。假设您将缓冲区设置为 10。您会发现，当超出峰值限制限制时，API 不会立即返回错误。而是会缓冲请求（最高可达指定的数量），并在下一个合适的执行时段可用时立即处理缓冲的请求。bufferSize 的默认值为 0。

如果您运行多个 Edge Micro 进程

允许的请求数量取决于正在运行的 Edge Micro 工作器进程的数量。高峰控制会计算每个工作器进程允许的请求数量。默认情况下，Edge Micro 进程的数量等于安装了 Edge Micro 的机器上的 CPU 数量。但是，您可以使用 start 命令中的 --processes 选项来配置启动 Edge Micro 时工作器进程的数量。例如，如果您希望在给定时间段内有 100 个请求触发高峰控制，并且您使用 --processes 4 选项启动 Edge Microgate，请在高峰控制配置中设置 allow: 25。总而言之，经验法则是将 allow 配置参数设置为“所需的高峰控制数量 / 进程数量”。

使用配额插件

配额用于指定在一小时、一天、一周或一个月内允许应用向 API 提交的请求消息数量。当应用达到配额限制时，后续的 API 调用会被拒绝。另请参阅高峰控制和配额之间有何区别。

添加配额插件

请参阅添加和配置插件。

Apigee Edge 中的产品配置

您可以在配置 API 产品的 Apigee Edge 界面中配置配额。您需要知道哪个产品包含您希望通过配额加以限制的微网关感知型代理。此产品必须添加到开发者应用中。当您在开发者应用中进行 API 调用并使用密钥进行身份验证时，系统会将配额应用于这些 API 调用。

  1. 登录您的 Apigee Edge 组织帐号。
  2. 在 Edge 界面中，打开与要应用配额的微网关感知型代理相关联的产品。
    1. 在界面中，从“发布”菜单中选择商品。
    2. 打开包含您要应用配额的 API 的产品。
    3. 点击修改。
    4. 在“配额”字段中，指定配额间隔。例如，每分钟 100 个请求。或者每 2 小时 50,000 个请求。

  1. 点击保存。
  2. 确保产品已添加到开发者应用中。您需要使用此应用的密钥才能进行经过身份验证的 API 调用。

配额配置示例

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

配额的配置选项

如需配置配额插件，请将 quotas 元素添加到您的配置文件中，如以下示例所示： 

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
    isHTTPStatusTooManyRequestEnabled: true
...
选项 说明
bufferSize

(Integer) 通过 bufferSize 配置，您可以调整 Edge Microgate 将其配额数量与 Apigee Edge 同步的频率。如需了解 bufferSize，请参考以下示例配置： 

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

默认情况下，如果配额间隔设置为“分钟”，则微网关每 5 秒将其配额计数器与 Apigee Edge 同步。上述配置表示，如果 API 产品中将配额间隔设置为“分钟”，Edge Microgate 将与 Edge 同步，以便在每 500 个请求或 5 秒后（二者取其先）获取当前的配额数量。如需了解详情，请参阅了解配额的统计方式。

允许的时间单位包括：minute、hour、day、week、month 和 default。

isHTTPStatusTooManyRequestEnabled

如果存在配额违规，将配额插件配置为返回 HTTP 429 响应状态而不是状态 403。

默认值：false。默认情况下，或者如果标志设置为 false，当超出配额时，配额会返回 HTTP 状态 403。

如果该标志设置为 true，则超出配额时，配额会返回 HTTP 状态 429。

如需将默认的 HTTP 返回状态更改为 429，请使用以下配置： 

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true
...
failOpen 启用此功能后，如果发生配额处理错误或向 Edge 的“配额应用”请求无法更新远程配额计数器，系统将仅根据本地计数处理配额，直到下次成功同步远程配额为止。在这两种情况下，请求对象中都会设置 quota-failed-open 标志。

如需启用配额“应急开启”功能，请设置以下配置： 

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId 将此标志设置为 true 可在配额响应中启用 MP（消息处理器）ID 日志记录。

如需使用此功能，您必须设置以下配置： 

edgemicro:
...
quotas:
  useDebugMpId: true
...

设置 useDebugMpId 后，Edge 的配额响应将包含 MP ID 并由 Edge Microgate 记录。例如： 

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis 如果设置为 true，则插件使用 Redis 作为配额后备存储。如需了解详情，请参阅使用 Redis 后备存储空间中的配额。

了解配额的统计方式

默认情况下，如果配额间隔设置为“分钟”，则微网关每 5 秒将其配额计数器与 Apigee Edge 同步。如果间隔设置为高于“分钟”的级别（例如“周”或“月”），则默认刷新周期为 1 分钟。

请务必注意，您可以在 Apigee Edge 上定义的 API 产品中指定配额间隔。配额间隔用于指定一分钟、一小时、一天、一周或一个月内允许的请求数量。例如，产品 A 的配额间隔可能是每分钟 100 个请求，而产品 B 的配额间隔可能是每小时 10,000 个请求。

Edge Microgate quota 插件的 YAML 配置不会设置配额间隔，而是用于调整本地 Edge Microgate 实例将其配额数量与 Apigee Edge 同步的频率。

例如，假设在 Apigee Edge 中定义有三个 API 产品，并指定了以下配额间隔：

  • 产品 A 的配额为每分钟 100 个请求
  • 产品 B 的配额为每小时 5000 个请求
  • 产品 C 的配额为每月 100 万个请求

考虑到这些配额设置，应该如何配置 Edge Microgate quota 插件？最佳做法是配置 Edge Microgate 的同步间隔，使其低于 API 产品中定义的配额间隔。例如： 

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

此配置为上述 API 产品定义了以下同步间隔：

  • 产品 A 的时间间隔设置为“分钟”。Edge Microgate 会在每 50 次请求或 5 秒（二者取其先）后同步到 Edge。
  • 产品 B 的时间间隔设置为“小时”。Edge Microgate 会在每 2000 次请求或 1 分钟（以先到者为准）后同步到 Edge。
  • 产品 C 的时间间隔设置为“月”。Edge Microgate 会在每个请求后或 1 分钟（以先到者为准）后同步到 Edge。

每当微网关实例与 Edge 同步时，微网关的配额计数都会设置为检索到的配额计数。

通过 bufferSize 设置，您可以调整配额计数器与 Edge 的同步方式。在高流量情况下，bufferSize 设置允许缓冲区计数器在基于时间的默认同步触发之前进行同步。

了解配额范围

配额计数的范围限定为组织中的某个环境。为了实现此范围，Edge Microgate 会创建一个由“org + env + appName + productName”组合而成的配额标识符。

将 Redis 后备存储空间用于配额

如需将 Redis 后备存储空间用于配额，请使用用于同步功能的相同配置。以下是使用 Redis 进行配额存储所需的基本配置：

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
如需详细了解 edgemicro.redis* 参数，请参阅使用同步器。

测试配额插件

超出配额时，系统会向客户端返回 HTTP 403 状态以及以下消息：

{"error": "exceeded quota"}

高峰控制期和配额之间有何区别？

请务必针对手头的工作选择合适的工具。配额政策用于配置在一小时、一天、一周或一个月内允许客户端应用向 API 提交的请求消息数量。配额政策通过维护记录传入请求的分布式计数器对客户端应用强制执行用量限制。

使用配额政策来强制执行与开发者和合作伙伴的业务合同或服务等级协议 (SLA)，而不是用于运营流量管理。例如，可以使用配额来限制免费服务的流量，同时允许付费客户完全访问。

使用高峰控制来防范 API 流量突然激增。通常情况下，高峰控制用于抵御潜在的 DDoS 攻击或其他恶意攻击。