此页面由 Cloud Translation API 翻译。

开发自定义插件

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

Edge Microgateway v. 3.1.x

受众群体

本主题面向希望通过编写代码来扩展 Edge Microgateway 功能的开发者自定义插件。如果您想编写一个新插件，具备 JavaScript 和 Node.js 方面的经验必填字段。

什么是自定义 Edge Microgateway 插件？

插件是一个 Node.js 模块，可以为 Edge Microgateway 添加功能。插件模块遵循一致的模式并存储在 Edge Microgateway 已知的位置，使以便自动发现并运行在构建容器时，系统会提供几种安装 Edge Microgateway。其中包括身份验证、高峰控制、配额和分析。如需了解这些现有插件，请参阅使用插件。

您可以通过编写自定义插件。默认情况下，Edge Microgateway 本质上是一个安全的直通代理，向目标服务传递请求和响应，向目标服务传递请求和响应。借助自定义插件，您可以与流经微网关的请求和响应进行交互。

自定义插件代码放置位置

Edge Microgateway 安装过程中包含自定义插件文件夹此处：

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

其中 [prefix] 是 npm 前缀目录，如下所示：如“Edge Microgateway 的安装位置”中所述参见安装 Edge Microgateway。

您可以更改此默认插件目录。请参阅查找位置插件。

查看预定义插件

在尝试开发自己的插件之前，最好先检查满足您的要求。这些插件位于以下位置：

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

其中 [prefix] 是 npm 前缀目录。请参阅以及“Edge Microgateway 的安装位置”请参阅安装 Edge Microgateway。

有关详情，另请参阅预定义 Edge Microgateway 提供的插件。

编写一个简单的插件

在本部分中，我们将介绍创建简单插件所需的步骤。此插件使用字符串“Hello, World!”覆盖响应数据（无论是什么）并将其输出到终端。

如果 Edge Microgateway 正在运行，请立即将其停止：
```
edgemicro stop
```
cd 添加到自定义插件目录：
cd [prefix]/lib/node_modules/edgemicro/plugins

其中 [prefix] 是 npm 前缀目录如“Edge Microgateway 的安装位置”中所述参见安装 Edge Microgateway。
新建一个名为 response-override 和 cd 的插件项目更改为：
```
mkdir response-override && cd response-override
```
创建一个新的 Node.js 项目：
```
npm init
```
多次按“返回”键可接受默认值。
使用文本编辑器创建名为 index.js 的新文件。
将以下代码复制到 index.js 中，然后保存该文件。
```
'use strict';
var debug = require('debug')

module.exports.init = function(config, logger, stats) {

  return {
   
    ondata_response: function(req, res, data, next) {
      debug('***** plugin ondata_response');
      next(null, null);
    },
    
    onend_response: function(req, res, data, next) {
      debug('***** plugin onend_response');
      next(null, "Hello, World!\n\n");
    }
  };
}
```
注意：插件函数 (*_response) 事件处理脚本。ondata_response 函数每当 Edge Microgateway 收到数据块时，都会调用。通过 onend_response 函数会在以下情况下调用：响应数据。

注意：重要提示：所有插件函数都需要 next() 函数。这个函数会传递 error（第一个参数）和 data（第二个参数）参数）。请注意，在此示例中， ondata_response 中的 data 参数是 null。将此参数设置为 null 可以让我们通过 onend_response 中的响应数据。如果我们没有将 null，则默认情况下，数据会传递到我们是否会在响应中覆盖 onend_response。
现在，您已经创建了一个插件，需要将其添加到 Edge Microgateway 配置中。打开文件 $HOME/.edgemicro/[org]-[env]-config.yaml，其中 org 和 env 是您的 Edge 组织和环境名称。
将 response-override 插件添加到 plugins:sequence 元素中如下所示。
```
      ...
      
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - response-override
          
      ...
```
注意：注意：插件将按照它们会显示在 plugins:sequence 列表中。
重启 Edge Microgateway。
通过 Edge Microgateway 调用 API。（此 API 调用假定您已设置相同的如设置 API 密钥安全性的教程中所述，并配置 Edge Microgateway：
```
curl -H 'x-api-key: uAM4gBSb6YoMvTHfx5lXJizYIpr5Jd' http://localhost:8000/hello/echo
Hello, World!
```

插件剖析

以下 Edge Microgateway 示例插件展示了在开发自己的插件。本部分讨论的示例插件的源代码是 plugins/header-uppercase/index.js.内

插件是标准 NPM 模块，具有 package.json 和 index.js 放在根文件夹中
插件必须导出 init() 函数。
init() 函数接受三个参数：config、 logger 和 stats。“插件”部分介绍了这些参数 init() 函数参数中。
init() 会返回一个包含已命名函数处理程序的对象，调用某些事件在请求的生命周期内发生。

事件处理脚本函数

插件必须实现上述部分或全部事件处理脚本函数。实施这些要素函数由您自己决定。任何给定的函数都是可选的，典型的插件将在是这些函数的一个子集。

请求流事件处理脚本

在 Edge Microgateway 中，这些函数在请求事件上调用。

onrequest
ondata_request
onend_request
onclose_request
onerror_request

onrequest 函数

在客户端请求开始时调用。此函数在 Edge Microgateway 收到请求时。借助此函数，您可以访问请求标头网址、查询参数和 HTTP 方法。如果您调用 next 并向其传递真实的第一个参数（例如 Error 实例），则请求处理将停止，并且不会启动目标请求。

示例：

onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-start'] = Date.now();
      next();
    }

ondata_request 函数

在从客户端收到数据块时调用。将请求数据传递给下一个。序列中最后一个插件的返回值将发送到目标。典型用例（如下所示）是先转换请求数据，然后再发送目标。

示例：

ondata_request: function(req, res, data, next) {
      debug('plugin ondata_request ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }

onend_request 函数

在已从客户端收到所有请求数据时调用。

示例：

onend_request: function(req, res, data, next) {
      debug('plugin onend_request');
      next(null, data);
    }

onclose_request 函数

表示客户端连接已关闭。在下列情况下，您可以使用此函数：则客户端连接不可靠。当与客户端的套接字连接已关闭。

示例：

onclose_request: function(req, res, next) {
      debug('plugin onclose_request');
      next();
    }

onerror_request 函数

在接收客户端请求时出错时调用。

示例：

onerror_request: function(req, res, err, next) {
      debug('plugin onerror_request ' + err);
      next();
    }

响应流事件处理脚本

这些函数在 Edge Microgateway 中的响应事件上调用。

onresponse
ondata_response
onend_response
onclose_response
onerror_response

onresponse 函数

在目标响应开始时调用。此函数在 Edge Microgateway 收到响应时。此函数让您可以访问响应标头和状态代码。

示例：

onresponse: function(req, res, next) {      
    debug('plugin onresponse');     
    res.setHeader('x-foo-response-time', Date.now() - req.headers['x-foo-request-start'])    
    next();    
}

ondata_response 函数

在从目标收到数据块时调用。

示例：

ondata_response: function(req, res, data, next) {
      debug('plugin ondata_response ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }

onend_response 函数

在收到来自目标的所有响应数据时调用。

示例：

onend_response: function(req, res, data, next) {
      debug('plugin onend_response');
      next(null, data);
    }

onclose_response 函数

表示目标连接已关闭。在下列情况下，您可以使用此函数：目标连接不可靠。当与目标的套接字连接处于已关闭。

示例：

onclose_response: function(req, res, next) {
      debug('plugin onclose_response');
      next();
    }

onerror_response 函数

在接收目标响应时出错时调用。

示例：

onerror_response: function(req, res, err, next) {
      debug('plugin onerror_response ' + err);
      next();
    }

您需要了解的插件事件处理脚本函数

系统会调用插件事件处理脚本函数，以响应在事件发生时 Edge Microgateway 会处理给定的 API 请求。

每个 init() 函数处理程序（ondata_request、 ondata_response 等）完成调用后，必须调用 next() 回调处理。如果您不调用 next()，系统将停止处理并发出请求会挂起。
next() 的第一个参数可能是一个错误，会导致请求处理以终止。
ondata_ 和 onend_ 处理程序必须调用 next()，其第二个参数包含要传递给目标的数据或客户端。如果插件正在缓冲且没有足够的数据转换。
请注意，插件的单个实例用于为所有请求和响应提供服务。如果插件希望在调用之间保留每个请求的状态，则可以在属性添加到提供的 request 对象 (req)，其生命周期是指 API 调用的时长。
请注意捕获所有错误并调用包含相应错误的 next()。失败调用 next() 将导致 API 调用挂起。
请注意不要引入内存泄漏问题，因为这可能会影响 Edge 的整体性能 Microgateway，并且在内存耗尽时导致其崩溃。
请注意遵循 Node.js 模型，不要在主线程中执行计算密集型任务线程，因为这可能会对 Edge Microgateway 的性能产生负面影响。

关于插件 init() 函数

本部分介绍了传递给 init() 函数的参数： config、logger 和 stats。

config

将 Edge Microgateway 配置文件与从 Apigee Edge 下载的信息，例如产品和配额。您可以此对象中的插件特定配置：config.<plugin-name>。

添加名为 param 且值为 foo 的配置参数添加到名为 response-override 的插件，请将以下内容放入 default.yaml 中文件：

response-override:
    param: foo

然后，您可以在插件代码中访问该参数，如下所示：

// Called when response data is received
    ondata_response: function(req, res, data, next) {
      debug('***** plugin ondata_response');
      debug('***** plugin ondata_response: config.param: ' + config.param);
      next(null, data);
    },

在这种情况下，您会在插件调试输出中看到输出的 foo：

Sun, 13 Dec 2015 21:25:08 GMT plugin:response-override ***** plugin ondata_response: config.param: foo

logger

系统日志记录器。当前使用的日志记录器会导出这些函数，其中对象可以是字符串、HTTP 请求、HTTP 响应或 Error 实例。

info(object, message)
warn(object, message)
error(object, message)

stats

保存请求、响应、错误和其他汇总统计信息的对象与流经微网关实例的请求和响应相关。

treqErrors - 出错的目标请求的数量。
treqErrors - 出错的目标响应数量。
statusCodes - 一个包含响应代码计数的对象：

{
  1: number of target responses with 1xx response codes
  2: number of target responses with 2xx response codes
  3: number of target responses with 3xx response codes
  4: number of target responses with 4xx response codes
  5: number of target responses with 5xx response codes
  }

requests - 请求总数。
responses - 响应总数。
connections - 活跃目标连接的数量。

关于 next() 函数

所有插件方法都必须调用 next() 才能继续处理（否则插件进程将挂起）。在请求生命周期中，调用的第一个方法是 onrequest()。接下来要调用的方法是 ondata_request() 方法；不过，仅在请求包含数据时调用 ondata_request，如例如 POST 请求的情况调用的下一个方法将是 onend_request()：在请求处理完成时调用。通过 onerror_* 函数仅在出现错误时调用，允许您如果您愿意，可以使用自定义代码处理错误。

假设数据在请求中发送，并且调用了 ondata_request()。通知该函数使用以下两个参数调用 next()：

next(null, data);

按照惯例，第一个参数用于传达错误信息，然后处理脚本。将其设置为 null 后，参数，我们说没有错误，请求处理应该可以正常进行。如果该参数为 true（例如 Error 对象），则请求处理将停止，并且请求发送到目标。

第二个参数将请求数据传递给链中的下一个函数。如果您不那么请求数据将原封不动地传递给 API 的目标。不过，您可以在此方法中修改请求数据，并将修改后的发送到目标。例如，如果请求数据是 XML，而目标需要 JSON，然后，您可以向 ondata_request() 方法添加代码，以便 (a) 更改将请求标头的 Content-Type 转换为 application/json，并转换请求数据转换为 JSON 格式（例如，您可以使用 Node.js xml2json 转换器）。

我们来看一看具体效果如何：

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  next(null, translated_data);
},

在这种情况下，请求数据（假定为 XML）将转换为 JSON，并且转换后的数据通过 next() 传递给请求链中的下一个函数，然后再传递给后端目标。

请注意，您可以再添加一个调试语句来输出转换后的数据以进行调试目的。例如：

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  debug('****** plugin ondata_response: translated_json: ' + translated_json);
  next(null, translated_data);
},

简介插件处理程序执行顺序

为 Edge Microgateway 编写插件时，您需要了解插件使用的顺序事件处理脚本的执行情况

需要注意的一点是，在 Microgateway 配置文件时，请求处理程序按升序执行，而响应处理程序按降序执行。

以下示例旨在帮助您了解此执行序列。

1. 创建三个简单的插件

请参考以下插件。它的作用就是在事件处理脚本触发时，调用：

plugins/plugin-1/index.js

module.exports.init = function(config, logger, stats) {

  return {

    onrequest: function(req, res, next) {
      console.log('plugin-1: onrequest');
      next();
    },

    onend_request: function(req, res, data, next) {
      console.log('plugin-1: onend_request');
      next(null, data);
    },

    ondata_response: function(req, res, data, next) {
      console.log('plugin-1: ondata_response ' + data.length);
      next(null, data);
    },

    onend_response: function(req, res, data, next) {
      console.log('plugin-1: onend_response');
      next(null, data);
    }
  };
}

现在，考虑再创建两个插件，即 plugin-2 和 plugin-3，相同的代码（不同之处是需要将 console.log() 语句更改为 plugin-2）和 plugin-3）。

2. 查看插件代码

导出的插件会在 <microgateway-root-dir>/plugins/plugin-1/index.js 是事件处理脚本，在请求和响应处理期间的特定时间执行。例如： onrequest 执行收到的请求标头的第一个字节。在此期间， onend_response 会在收到响应数据的最后一个字节之后执行。

看一下处理程序 ondata_response - 每当有响应数据块时，系统都会调用它。需要注意的一点是，响应数据不一定要一次。相反，数据可能会以任意长度的数据块接收。

3. 将插件添加到插件序列

继续这个示例，我们将插件添加到 Edge 中的插件序列中， Microgateway 配置文件 (~./edgemicro/config.yaml)，如下所示。序列是非常重要。它定义了插件处理程序的执行顺序。

  plugins:
    dir: ../plugins
    sequence:
      - plugin-1
      - plugin-2
      - plugin-3

4. 检查调试输出

现在，我们来看看调用这些插件时产生的输出。还有需要注意以下几点重要事项：

该插件按 Edge Microgateway 配置文件的顺序排列 (~./edgemicro/config.yaml) 用于指定事件处理脚本的顺序调用。
请求处理程序按升序调用（即在插件序列 1、2、3 中显示）。
响应处理程序按降序（3、2、1）调用。
对于需要处理的每个数据块，系统都会调用一次 ondata_response 处理程序。在此示例中（输出如下所示）中，收到了两个分块。

下面是使用这三个插件并且发送请求时生成的调试输出示例通过 Edge Microgateway 访问 Wi-Fi。只需注意调用处理程序的顺序即可：

  plugin-1: onrequest
  plugin-2: onrequest
  plugin-3: onrequest

  plugin-1: onend_request
  plugin-2: onend_request
  plugin-3: onend_request

  plugin-3: ondata_response 931
  plugin-2: ondata_response 931
  plugin-1: ondata_response 931

  plugin-3: ondata_response 1808
  plugin-3: onend_response

  plugin-2: ondata_response 1808
  plugin-2: onend_response

  plugin-1: ondata_response 1808
  plugin-1: onend_response

摘要

当您尝试实现自定义插件功能，例如累积和转换请求或响应数据。

请记住，请求处理程序的执行顺序与插件在 Google Cloud 上的而响应处理程序会在顺序相反。

关于在插件中使用全局变量

发送到 Edge Microgateway 的每个请求都会发送到插件的同一实例；因此，来自另一个客户端的第二个请求的状态将覆盖第一个请求的状态。只有保存插件状态的方式是将状态存储在请求或响应对象（其的生命周期限制为请求的有效期）。

在插件中重写目标网址

添加此模块的版本：v2.3.3

您可以通过修改这些变量来动态替换插件中的默认目标网址 req.targetHostname 和 req.targetPath。

添加此模块的版本：v2.4.x

您还可以替换目标端点端口，并选择 HTTP 或 HTTPS。修改这些内容变量：req.targetPort 和 req.targetSecure.要选择 HTTPS，请将 req.targetSecure 设置为 true;对于 HTTP，请将此参数设置为 false。如果您将 req.targetSecure 设置为请参阅这篇讨论讨论帖。

Edge Microgateway 中添加了一个名为 eurekaclient 的示例插件。这个插件演示了如何使用 req.targetPort 和 req.targetSecure 变量，以及说明了 Edge Microgateway 如何使用 Eureka 服务执行动态端点查找端点目录

示例插件

这些插件随 Edge Microgateway 安装提供。您可以在在此处安装 Edge Microgateway：

[prefix]/lib/node_modules/edgemicro/plugins