使用插件

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

Edge Microgateway v. 3.2.x

受众群体

本主题面向希望使用随微网关安装的现有插件的 Edge Microgateway 运营商。此外，本文还详细讨论了峰值抑制和配额插件（两者都包含在安装中）。如果您是想要开发新插件的开发者，请参阅开发自定义插件。

什么是 Edge Microgateway 插件？

插件是一种 Node.js 模块，可为 Edge Microgateway 添加功能。插件模块遵循一致的模式，并存储在 Edge Microgateway 已知的位置，从而使微网关能够自动发现并加载它们。Edge Microgateway 包含多个现有插件，您还可以创建自定义插件，如开发自定义插件中所述。

与 Edge Microgateway 捆绑的现有插件

Edge Microgateway 在安装时附带了多个现有插件。其中包括：

插件 默认处于启用状态 说明
分析 是 将分析数据从 Edge Microgateway 发送到 Apigee Edge。
oauth 是 向 Edge Microgateway 添加 OAuth 令牌和 API 密钥验证。请参阅设置和配置 Edge Microgateway。
配额 否 对 Edge Microgateway 的请求强制执行配额。使用 Apigee Edge 存储和管理配额。请参阅使用配额插件。
spikearrest 否 防范突发流量高峰和 DoS 攻击。请参阅使用 Spike Arrest 插件。
header-uppercase 否 一个带有注释的示例代理，旨在作为指南帮助开发者编写自定义插件。 请参阅 Edge Microgateway 插件示例。
accumulate-request 否 在将请求数据传递给插件链中的下一个处理程序之前，将请求数据累积到单个对象中。有助于编写需要对单个累积请求内容对象进行操作的转换插件。
accumulate-response 否 在将响应数据传递给插件链中的下一个处理程序之前，将响应数据累积到单个对象中。有助于编写需要对单个累积的响应内容对象进行操作的转换插件。
transform-uppercase 否 转换请求或响应数据。此插件代表了转换插件的最佳实践实现。示例插件执行简单的转换（将请求或响应数据转换为大写）；不过，它很容易适应其他类型的转换，例如从 XML 到 JSON 的转换。
json2xml 否 根据 accept 或 content-type 标头转换请求或响应数据。如需了解详情，请参阅 GitHub 中的插件文档。
quota-memory 否 对 Edge Microgateway 的请求强制执行配额。在本地内存中存储和管理配额。
健康检查 否 返回有关 Edge Microgateway 进程的信息，例如内存用量、CPU 使用情况等。如需使用该插件，请在 Edge Microgateway 实例上调用网址 /healthcheck。此插件旨在作为示例，供您用来实现自己的健康检查插件。

在哪里可以找到现有插件

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

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

添加和配置插件

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

  1. 停止 Edge Microgateway。
  2. 打开 Edge Microgateway 配置文件。如需了解详情，请参阅 进行配置更改。
  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. 配置插件。某些插件具有可在配置文件中配置的可选参数。例如，您可以添加以下 stanza 来配置 spike arrest 插件。如需了解详情，请参阅使用流量突增抑制插件。 
    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 Microgateway。

特定于插件的配置

您可以在此目录中创建特定于插件的配置，以替换配置文件中指定的插件参数：

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

其中，[prefix] 是 npm 前缀目录。如果您找不到此目录，请参阅 Edge Microgateway 安装在何处。

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

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

使用突峰抑制插件

spike arrest 插件可防范流量激增。它会限制 Edge Microgateway 实例处理的请求数。

添加 Spike Arrest 插件

请参阅添加和配置插件。

峰值抑制的配置示例

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：峰值抑制执行窗口重置的频率。有效值为 second 或 minute。
  • allow：在 timeUnit 期间允许的最大请求数。另请参阅如果您运行多个 Edge Micro 进程。
  • bufferSize：（可选，默认值为 0）如果 bufferSize > 0，则突峰流量抑制功能会在缓冲区中存储相应数量的请求。一旦出现下一个执行“窗口”，系统将首先处理缓冲的请求。另请参阅添加缓冲区。

Spike Arrest 的工作原理是什么？

您可将 Spike Arrest 视为一种用于避免流量高峰的方法，而不是将流量限制为特定请求数的方法。您的 API 和后端可以处理一定量的流量，而高峰控制政策有助于将流量平滑地保持在您所需的常规量。

运行时 Spike Arrest 行为与您期望输入的每分钟或每秒字面量值产生的行为有所不同。

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

spikearrest:
   timeUnit: minute
   allow: 30

在测试时，您可能认为您可以在 1 秒内发送 30 个请求，只要在 1 分钟内即可。但该政策并非这样执行这种设置的。如果您思考一下就会明白，某些环境中 1 秒钟内 30 个请求会被视为是一个小型高峰。

那么，然后会怎么样呢？为防止出现类似高峰的行为，Spike Arrest 会将您的设置划分为若干更小的时间间隔，从而平滑处理允许的流量，如下所示：

每分钟费率

每分钟速率可以以秒为时间间隔，平滑发送允许的请求。例如，每分钟 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 数量。不过，您可以在启动 Edge Micro 时使用 start 命令中的 --processes 选项来配置工作器进程的数量。例如，如果您希望在给定时间段内达到 100 个请求时触发峰值流量限制，并且您使用 --processes 4 选项启动 Edge Microgateway，则在峰值流量限制配置中设置 allow: 25。总而言之，经验法则是将 allow 配置参数设置为“所需的尖峰抑制次数 / 进程数”的值。

使用配额插件

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

添加配额插件

请参阅添加和配置插件。

Apigee Edge 中的产品配置

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

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

  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
...
选项 说明
bufferSize

（整数）通过 bufferSize 配置，您可以调整 Edge Microgateway 与 Apigee Edge 同步配额计数的频率。为了理解 bufferSize，请考虑以下示例配置： 

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

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

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

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

如需启用配额“故障开放”功能，请设置以下配置： 

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

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

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

如果设置了 useDebugMpId，来自 Edge 的配额响应将包含 MP ID，并且 Edge Microgateway 会记录这些响应。例如： 

{
    "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 Microgateway quota 插件的 YAML 配置不会设置配额间隔；相反，它提供了一种调整本地 Edge Microgateway 实例与 Apigee Edge 同步其配额计数的频率的方法。

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

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

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

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

此配置为之前描述的 API 产品定义了以下同步间隔：

  • 商品 A 设置为“分钟”间隔。Edge Microgateway 将在每第 50 个请求或每 5 秒后（以先到者为准）同步到 Edge。
  • 商品 B 设置为“小时”间隔。Edge Microgateway 将在每第 2000 个请求或每 1 分钟后（以先到者为准）同步到 Edge。
  • 产品 C 设置为“月”间隔。Edge Microgateway 将在每个请求后或每 1 分钟后（以先到者为准）同步到 Edge。

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

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

了解配额范围

配额数量的范围限定为组织中的环境。为了实现此范围，Edge Microgateway 会创建一个配额标识符，该标识符是“组织 + 环境 + 应用名称 + 产品名称”的组合。

使用 Redis 后端存储区来存储配额

如需使用 Redis 后端存储区来存储配额，请使用与同步器功能相同的配置。以下是使用 Redis 进行配额存储所需的基本配置： 

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

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

测试配额插件

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

{"error": "exceeded quota"}

Spike Arrest 和配额之间的区别是什么？

为手头的任务选择合适的工具非常重要。配额政策用于配置允许客户端应用在一小时、一日、一周或一个月内提交给 API 的请求消息的数量。配额政策通过维护分布式计数器计算传入请求，从而对客户端应用强制执行使用限制。

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

使用 Spike Arrest 可防止 API 流量突然激增。通常，峰值抑制用于防范可能的 DDoS 攻击或其他恶意攻击。