本頁面由 Cloud Translation API 翻譯而成。

開發自訂外掛程式

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

Edge Microgateway 3.1.5 以上版本

目標對象

本主題適用於希望以書面方式擴充 Edge Microgateway 功能的開發人員自訂外掛程式如想編寫新的外掛程式，具備 JavaScript 和 Node.js 的經驗這通常代表交易不會十分要求關聯語意

什麼是自訂 Edge Microgateway 外掛程式？

外掛程式是一種 Node.js 模組，可為 Edge Microgateway 新增功能。外掛程式模組遵循一致模式，並儲存在 Edge Microgateway 上的已知位置，藉此達成目的以便自動探索及執行當您下載容器時安裝 Edge Microgateway。這些外掛程式包括各種外掛程式數據分析如需這些現有外掛程式的說明，請參閱「使用外掛程式」。

您可以為微門安裝新功能，例如：自訂外掛程式」一文。根據預設，Edge Microgateway 基本上就是安全直通 Proxy，會傳送與目標服務未經變更的要求和回應。使用自訂外掛程式透過程式與進入微門閘道的要求和回應互動。

自訂外掛程式程式碼的位置

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。

詳情請參閱「預先定義隨附的外掛程式

編寫簡易外掛程式

本節將逐步引導您建立簡易外掛程式。這個外掛程式會以「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 金鑰安全性」教學課程一樣，瞭解如何設定 API 金鑰安全性並設定 Edge Microgateway：
```
curl -H 'x-api-key: uAM4gBSb6YoMvTHfx5lXJizYIpr5Jd' http://localhost:8000/hello/echo
Hello, World!
```

外掛程式剖析

下列 Edge Microgateway 範例外掛程式說明開發您自己的外掛程式本節探討的範例外掛程式原始碼為 plugins/header-uppercase/index.js.

外掛程式是具有 package.json 和 index.js 的標準 NPM 模組複製到根資料夾
外掛程式必須匯出 init() 函式。
init() 函式會使用三個引數：config、 logger 和 stats。外掛程式會詳細說明這些引數 init() 函式引數即可。
init() 會傳回含有已命名函式處理常式的物件；在呼叫該函式時，都只會發生在要求的生命週期內

事件處理常式函式

外掛程式必須實作部分或所有的事件處理常式函式。實作前述項目功能由您決定任何指定的函式都屬於選用性質，一般外掛程式會在也就是這些函式的子集

要求流程事件處理常式

系統會在 Edge Microgateway 中的要求事件上呼叫這些函式。

onrequest
ondata_request
onend_request
onclose_request
onerror_request

onrequest 函式

在用戶端要求開始時呼叫。這個函式會在要求。這個函式可讓您存取要求標頭網址、查詢參數和 HTTP 方法如果您接著呼叫了錯誤的執行個體)，則要求會停止處理程序，而且目標要求不會開始。

範例：

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 的物件中。

新增名為 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

個人中心可以存取合併的微閘道設定，並下載 Apigee Edge 資料子項物件 config.emgConfigs。例如：您可以在 init 函式中存取這項設定資料如下所示：

module.exports.init = function(config, logger, stats) {
   let emgconfigs = config.emgConfigs;

敬上

注意： 已新增 emgConfigs 物件。金鑰名稱「emgConfigs」為預留名稱，因此無法使用，用於在 YAML 設定中的外掛程式設定下方定義任何其他設定檔案。如果系統就會在執行階段覆寫該值。

以下是 emgConfigs 包含的資料範例：

{
    edgemicro:
    {
        port: 8000,
        max_connections: 1000,
        config_change_poll_interval: 600,
        logging:
        {
            level: 'error',
            dir: '/var/tmp',
            stats_log_interval: 60,
            rotate_interval: 24,
            stack_trace: false
        },
        plugins: { sequence: [Array] },
        global: { org: 'Your Org', env: 'test' }
    },
    headers:
    {
        'x-forwarded-for': true,
        'x-forwarded-host': true,
        'x-request-id': true,
        'x-response-time': true,
        via: true
    },
    proxies:
    [    {
                max_connections: 1000,
                name: 'edgemicro_delayed',
                revision: '1',
                proxy_name: 'default',
                base_path: '/edgemicro_delayed',
                target_name: 'default',
                url: 'https://httpbin.org/delay/10',
                timeout: 0
            }
    ],
    product_to_proxy: { EdgeMicroTestProduct: [ 'edgemicro-auth','edgemicro_delayed',] },
    product_to_scopes: {prod4: [ 'Admin', 'Guest', 'Student' ] },
    product_to_api_resource: { EdgeMicroTestProduct: [ '/*' ] },
    _hash: 0,
    keys: { key: 'Your key', secret: 'Your key ' },
    uid: 'Internally generated uuid',
    targets: []
  }

Logger

系統記錄器。目前使用的記錄器會匯出這些函式，而物件可字串、HTTP 要求、HTTP 回應或 Error 執行個體。

info(object, message)
warn(object, message)
error(object, message)
trace(object, message)
debug(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」，這就太可怕了引數，表示沒有任何錯誤，要求處理將正常進行。如果這個引數是悲觀的 (例如 Error 物件)，那麼要求處理停止，而要求傳送給目標

第二個參數將要求資料傳遞至鏈結中的下一個函式。如果您不這麼做則會將該要求資料直接傳遞至 API 的目標。不過，您可以在這個方法中修改要求資料，然後將修改過的接收所有要求的 HTTP 要求例如，如果要求資料是 XML，且目標預期使用 JSON，接著，您可以將程式碼新增至 ondata_request() 方法，以 (a) 變更將要求標頭的 Content-Type 轉換為 application/json，並轉換要求資料透過任何方式將模型寫入 JSON 檔 (例如使用 Node.js 從 NPM 取得的 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 外掛程式，必須瞭解外掛程式的順序事件處理常式的執行。

重點是，在 Edge 中指定外掛程式序列時 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您只需注意呼叫處理常式的順序：

  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

摘要

當您嘗試嘗試建立外掛程式時，必須瞭解外掛程式處理常式的呼叫順序實作自訂外掛程式功能，例如累積及轉換要求或回應資料。

請記得，要求處理常式會按照外掛程式執行的順序執行 Edge Microgateway 設定檔中指定的回應處理常式，且回應處理常式會在以相反順序

關於在外掛程式中使用全域變數

傳送至 Edge Microgateway 的每項要求都會傳送到同一個外掛程式的同一個執行個體；因此，另一個用戶端發出的第二個要求狀態就會覆寫第一個要求的狀態。唯一安全的環境儲存外掛程式狀態的方法是將狀態儲存在要求或回應物件的屬性中 ( 生命週期僅限於要求的時間)。

重寫外掛程式中的目標網址

已新增：v2.3.3

您可以修改這些變數，以動態方式覆寫外掛程式中的預設目標網址 req.targetHostname 和 req.targetPath。

已新增：v2.4.x

您也可以覆寫目標端點通訊埠，然後選擇 HTTP 或 HTTPS。修改這些項目變數中的變數：req.targetPort 和 req.targetSecure.如要選擇 HTTPS，請將 req.targetSecure 設為 true;請設為 false。如果您將 req.targetSecure 設為 true，請參閱此討論執行緒。

名為 eurekaclient 的範例外掛程式已新增至 Edge Microgateway。這個外掛程式會示範如何使用 req.targetPort 和 req.targetSecure 變數，並說明 Edge Microgateway 如何使用 Eureka 服務執行動態端點查詢端點目錄

外掛程式範例

這些外掛程式包含在 Edge Microgateway 安裝作業中。安裝在在此處安裝 Edge Microgateway：

[prefix]/lib/node_modules/edgemicro/plugins