使用插件

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

Edge Microgate v. 2.5.x

受众群体

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

什么是 Edge Microgate 插件？

插件是一个 Node.js 模块，用于向 Edge Microgate 添加功能。插件模块遵循一致的模式，并存储在 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	否	先将请求数据累积到单个对象中，然后再将相应数据传递到插件链中的下一个处理程序。适用于编写需要对单个累积的请求内容对象执行操作的转换插件。
累积响应	否	先将响应数据累积到单个对象中，然后再将数据传递到插件链中的下一个处理程序。适用于编写需要对单个累积的响应内容对象执行操作的转换插件。
转换（大写）	否	转换请求或响应数据。该插件代表了转换插件的最佳实践实现。示例插件会执行一些无关紧要的转换（将请求或响应数据转换为大写）；不过，它可以轻松地进行调整以执行其他类型的转换，例如从 XML 到 JSON。
json2xm	否	根据接受或内容类型标头转换请求或响应数据。如需了解详情，请参阅 GitHub 中的插件文档。
quota-memory	否	对发送到 Edge Microgate 的请求强制执行配额。在本地内存中存储和管理配额。
健康检查	否	返回有关 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

4. 配置插件。某些插件具有可选参数，您可以在配置文件中配置这些参数。例如，您可以添加以下节来配置“猛增现象”插件。如需了解详情，请参阅使用高峰控制插件。

   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
   

5. 保存文件。
6. 重启或重新加载 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 个请求会经过平滑处理，如下所示：

间隔时间为 1, 000 毫秒（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 中的产品配置

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

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

3. 点击保存。
4. 确保产品已添加到开发者应用中。您需要此应用的密钥才能调用经过身份验证的 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

配额的配置选项

配额插件没有其他配置选项。

测试配额插件

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

{"error": "exceeded quota"}

峰值限制与配额之间有什么区别？

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

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

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