使用外掛程式

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge Microgateway 3.1.5 以上版本

目標對象

本主題適用於想要使用微型閘道隨附外掛程式的 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 否 防範流量遽增和阻斷服務攻擊。請參閱「使用尖峰抑制外掛程式」。
header-uppercase 否 這個附註的範例 Proxy 可做為指引，協助開發人員編寫自訂外掛程式。 請參閱 Edge Microgateway 範例外掛程式。
accumulate-request 否 將要求資料累計至單一物件，然後將資料傳遞至外掛程式鏈中的下一個處理常式。適用於編寫需要對單一累積要求內容物件執行的轉換外掛程式。
accumulate-response 否 將回應資料累積到單一物件中，然後將資料傳遞至外掛程式鏈中的下一個處理常式。適用於編寫需要對單一累積回應內容物件執行的轉換外掛程式。
transform-uppercase 否 轉換要求或回應資料。這個外掛程式代表轉換外掛程式的最佳做法實作項目。範例外掛程式會執行簡單的轉換 (將要求或回應資料轉換為大寫)，但可以輕鬆調整，執行其他類型的轉換，例如 XML 轉 JSON。
json2xml 否 根據 Accept 或 Content-Type 標頭轉換要求或回應資料。詳情請參閱 GitHub 中的外掛程式說明文件。
quota-memory 否 對 Edge Microgateway 的要求強制執行配額。在本機記憶體中儲存及管理配額。
healthcheck 否 傳回 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. 設定外掛程式。部分外掛程式有選用參數，您可以在設定檔中設定。舉例來說，您可以新增下列節，設定尖峰抑制外掛程式。詳情請參閱使用尖峰抑制外掛程式。 
    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：尖峰抑制執行視窗的重設頻率。有效值為 second 或 minute。
  • allow：在 timeUnit 期間允許的要求數量上限。另請參閱「如果您執行多個 Edge Microgateway 程序」。
  • bufferSize：(選用，預設值為 0) 如果 bufferSize > 0，尖峰流量防護機制會將這個數量的要求儲存在緩衝區中。下一次執行「時間範圍」一到，系統就會先處理緩衝要求。另請參閱「新增緩衝區」。

尖峰抑制功能如何運作？

請將尖峰流量防護視為一般防範流量遽增的方法，而非將流量限制在特定要求數量的做法。API 和後端可處理一定量的流量，尖峰流量防範政策可協助您將流量平穩地控制在所需的一般量。

執行階段尖峰抑制行為與您輸入的每分鐘或每秒值可能不同。

舉例來說，假設您指定的速率為每分鐘 30 個要求，如下所示：

spikearrest:
   timeUnit: minute
   allow: 30

在測試中，您可能會認為只要要求是在一分鐘內送達，就能在一秒內傳送 30 個要求。但政策並非以這種方式強制執行設定。如果仔細想想，在某些環境中，1 秒內 30 項要求可視為小型尖峰。

那麼實際情況為何？為避免出現尖峰行為，尖峰抑制功能會將設定劃分為較小的間隔，藉此平穩允許的流量，如下所示：

每分鐘費率

系統會將每分鐘速率平滑化，轉換為允許間隔秒數的要求。舉例來說，每分鐘 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 Microgateway 程序

允許的要求數量取決於執行的 Edge Micro worker 程序數量。尖峰流量防護功能會計算每個工作站程序允許的請求數。根據預設，Edge Micro 程序數量等於安裝 Edge Micro 的機器 CPU 數量。不過，您可以在使用 start 指令啟動 Edge Micro 時，透過 --processes 選項設定工作站程序數量。舉例來說，如果您希望尖峰流量防護功能在特定時間範圍內觸發 100 個要求，並使用 --processes 4 選項啟動 Edge Microgateway，請在尖峰流量防護設定中設定 allow: 25。總而言之，經驗法則是將 allow config 參數設為「所需尖峰抑制計數 / 程序數」的值。

使用配額外掛程式

配額是指應用程式在一小時、一天、一週或一個月內，可向 API 提交的要求訊息數量。應用程式達到配額上限後，後續的 API 呼叫都會遭到拒絕。另請參閱「尖峰流量限制和配額有何不同？」。

新增配額外掛程式

請參閱「新增及設定外掛程式」。

在 Apigee Edge 中設定產品

您可以在 Apigee Edge 使用者介面中設定配額，並設定 API 產品。您需要知道哪個產品含有要以配額限制的微閘道感知 Proxy。這個產品必須新增至開發人員應用程式。當您使用開發人員應用程式中的金鑰進行驗證，並發出 API 呼叫時，系統會對這些 API 呼叫套用配額。

  1. 登入 Apigee Edge 機構帳戶。
  2. 在 Edge UI 中，開啟與要套用配額的微閘道感知 Proxy 相關聯的產品。
    1. 在使用者介面中，從「發布」選單選取「產品」。
    2. 開啟含有要套用配額的 API 的產品。
    3. 按一下 [編輯]。
    4. 在「配額」欄位中，指定配額間隔。例如，每分鐘 100 個要求。或每 2 小時 50,000 個要求。

  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 的配額為每小時 5000 個要求
  • 產品 C 的配額為每月 1000000 個要求

請考量這些配額設定，並說明應如何設定 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 會建立配額 ID，該 ID 是「org + env + appName + productName」的組合。

使用 Redis 後端儲存空間做為配額

如要將 Redis 後端儲存空間用於配額，請使用與 Synchronizer 功能相同的設定。如要使用 Redis 儲存配額，基本設定如下：

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

quotas:
  useRedis: true
如要瞭解 edgemicro.redis* 參數的詳細資料，請參閱「使用同步器」。

測試配額外掛程式

超過配額時，系統會將 HTTP 403 狀態傳回給用戶端，並附上以下訊息：

{"error": "exceeded quota"}

尖峰流量防護和配額有何不同？

請務必選擇適合目前工作的工具。配額政策會設定用戶端應用程式在每小時、每天、每週或每月，可向 API 提交的要求訊息數量。配額政策會維護分散式計數器，計算傳入的要求，藉此對用戶端應用程式強制執行用量限制。

使用配額政策來強制執行與開發人員和合作夥伴的商業合約或服務水準協議，而非用於營運流量管理。舉例來說，配額可用於限制免費服務的流量，同時允許付費客戶完整存取。

使用突增防範政策，防範 API 流量突然暴增。通常，尖峰抑制是用來防範可能的 DDoS 或其他惡意攻擊。