使用插件

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

Edge Microgateway v. 3.1.5 及更高版本

受众群体

本主题面向希望使用现有插件的 Edge Microgateway 操作者。 是与 microgateway 一起安装的。还讨论了高峰控制和配额插件， （安装时均包含这些信息）。如果您是一名开发者，希望开发新的 请参阅开发 自定义插件。

什么是 Edge Microgateway 插件？

插件是一个 Node.js 模块，可以为 Edge Microgateway 添加功能。插件模块 遵循一致的模式并存储在 Edge Microgateway 已知的位置，使 Microgateway 可以自动发现和加载这些网络。Edge Microgateway 包含几个现有的 插件，也可以创建自定义插件，如开发自定义插件中所述。

与 Edge 捆绑的现有插件 Microgateway

Edge Microgateway 在安装时提供了一些现有插件。这些 包括：

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

在哪里可以找到现有插件

与 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. 配置插件。某些插件具有可选参数，您可以在 配置文件例如，您可以添加以下节来配置高峰控制 插件。请参阅使用高峰控制插件 。 
    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

使用高峰控制插件

高峰控制插件可防范流量高峰。它会限制 由 Edge Microgateway 实例进行处理。

添加高峰控制插件

请参阅添加和配置插件。

以下项的配置示例： 高峰逮捕

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，峰值被捕 会将此数量的请求存储在缓冲区中。下次执行“window”时发生时， 缓存的请求会首先得到处理。另请参阅添加 缓冲区。

高峰逮捕是如何运作的？

将高峰控制视为一种通常用于防范流量高峰的方式，而不是作为一种 将流量限制在一定数量的请求以内。您的 API 和后端可以处理 高峰控制政策可帮助您平稳地调整为 。

运行时高峰停止行为不同于您在实际语言中看到的预期结果 每分钟或每秒的值

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

spikearrest:
   timeUnit: minute
   allow: 30

在测试中，您可能认为可以在 1 秒内发送 30 个请求，只要它们来自 我们一会儿见但此政策并非强制执行此设置的方式。仔细想想，有 30 在某些环境中，1 秒内发生的请求可能会被视为一次小峰值。

那么，然后会怎么样呢？为了防止出现类似峰值的行为，高峰控制会使允许的 将设置划分为更小的时间间隔，从而获得流量，具体如下：

每分钟费率

每分钟费率经过平滑处理为请求的允许时间间隔（以秒为单位）。例如，30 每分钟请求数进行平滑处理，如下所示：

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

每秒速率

每秒的速率会平滑到以毫秒为单位的允许请求中。例如： 每秒 10 个请求会进行平滑处理，如下所示：

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

超出限制时

如果请求数在指定的时间间隔内超出上限，则激增控制 会返回此错误消息及 HTTP 503 状态：

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

添加缓冲区

您可以选择向政策添加缓冲区。假设您将缓冲区设置为 10。 您会发现，当超过高峰控制时间时，API 不会立即返回错误 上限。而是会缓冲请求（最多为指定数量），缓冲的请求会 系统会尽快处理默认 bufferSize 为 0。

如果您同时运行多个 Edge Micro 进程

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

使用配额插件

配额指定允许应用向 API 提交的请求消息的数量 获得的流量当应用达到其配额限制时 API 调用会被拒绝。另请参阅 高峰控制和配额？

添加配额插件

请参阅添加和配置插件。

Apigee 中的产品配置 边缘

您可以在配置 API 产品的 Apigee Edge 界面中配置配额。须知事项 哪个产品包含您要通过配额进行限制的可感知微网关的代理。这个 产品必须添加到开发者应用中。当您进行使用 密钥，则配额将应用于这些 API 调用。

  1. 登录您的 Apigee Edge 组织账号。
  2. 在 Edge 界面中，打开与要连接到的可感知微网关的代理相关联的产品 您希望应用该配额
    1. 在界面中，从“发布”菜单中选择产品。
    2. 打开包含要应用配额的 API 的产品。
    3. 点击修改。
    4. 在“配额”字段中，指定配额间隔。例如，每 一分钟。或每 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

(Integer) bufferSize 配置可让您调整 Edge Microgateway 的频率 将其配额数量与 Apigee Edge 同步。为了了解 bufferSize 时，请参考以下示例配置： 

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

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

允许的时间 单位包括：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 配置不会设置配额 interval;而是提供了一种方法来调整本地 Edge Microgateway 的频率 实例同步其配额 数量。

例如，假设 Apigee Edge 中定义了三个 API 产品，它们的 指定的配额间隔：

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

了解了这些配额设置后，Edge Microgateway quota 插件应如何设计 ？最佳做法是配置 Edge Microgateway 并为其配置同步时间间隔， 低于 API 产品中定义的配额间隔。例如： 

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

此配置针对上述 API 产品定义了以下同步间隔 之前：

  • 产品 A 设置为“分钟”。Edge Microgateway 将在以下时间后同步到 Edge 每 50 个请求或 5 秒（以先到者为准）。
  • 产品 B 设置为“小时”。Edge Microgateway 将在以下时间后同步到 Edge 每 2, 000 个请求或 1 分钟，二者取其先。
  • 产品 C 设置为“月”。Edge Microgateway 将在以下时间后同步到 Edge 或每分钟（二者取其先）。

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

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

了解配额范围

配额数量仅与组织中的环境相关。为了实现这一范围 Edge Microgateway 会创建一个配额标识符，该标识符由“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 攻击或其他恶意攻击。