使用外掛程式

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

Edge Microgateway 3.2.x 版

適用對象

本主題適用於希望使用以 Microgateway 安裝的現有外掛程式的 Edge Microgateway 運算子。另外,也會詳細說明尖峰期間的逮捕與配額外掛程式 (兩者均包含在安裝中)。如果您是想要開發新外掛程式的開發人員,請參閱「開發自訂外掛程式」一文。

什麼是 Edge Microgateway 外掛程式?

外掛程式是一種 Node.js 模組,可為 Edge Microgateway 新增功能。外掛程式模組遵循一致的模式,並儲存在 Edge Microgateway 已知的位置,讓 Microgateway 能夠自動尋找和載入這些模組。Edge Microgateway 含有數個現有的外掛程式,您也可以建立自訂外掛程式,如「開發自訂外掛程式」一文所述。

Edge Microgateway 隨附的現有外掛程式

安裝時,Edge Microgateway 提供了部分現有的外掛程式。包括:

外掛程式 預設為啟用 說明
數據分析 這個外掛程式能將數據分析資料從 Edge Microgateway 傳送至 Apigee Edge。
oauth 將 OAuth 權杖和 API 金鑰驗證新增至 Edge Microgateway。請參閱「設定及設定 Edge Microgateway」。
配額 強制執行傳送至 Edge Microgateway 的要求配額。使用 Apigee Edge 儲存及管理配額。請參閱使用配額外掛程式
蜘蛛人 能防範流量遽增和 DoS 攻擊。請參閱使用尖峰流量防範外掛程式
標題大寫 註解的 Proxy 範例,可做為協助開發人員編寫自訂外掛程式的指南。請參閱 Edge Microgateway 範例外掛程式
累計要求 將要求資料累積至單一物件,然後再將資料傳送至外掛程式鏈中的下一個處理常式。如要編寫需要在單一累積要求內容物件上操作的轉換外掛程式,這個外掛程式就相當實用。
累計回應 將回應資料累積至單一物件,再將資料傳送至外掛程式鏈結中的下一個處理常式。如要編寫需要在單一累積回應內容物件上操作的轉換外掛程式,這個外掛程式就相當實用。
變形大寫 轉換要求或回應資料。這個外掛程式代表實作轉換外掛程式的最佳做法。範例外掛程式會執行一般轉換作業 (將要求或回應資料轉換為大寫),但也能輕鬆調整以執行其他類型的轉換作業,例如將 XML 轉換為 JSON。
json2xml 根據接受或 content-type 標頭轉換要求或回應資料。詳情請參閱 GitHub 中的外掛程式說明文件
配額記憶體 強制執行傳送至 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:尖峰執行期間的重設頻率。有效值為秒或分鐘。
  • allow:timeUnit 期間允許的要求數量上限。另請參閱「如果執行多個 Edge Micro 程序」一節。
  • bufferSize:(選用,預設值 = 0) 如果 bufferSize > 0,尖峰逮捕範圍會將此要求數量儲存在緩衝區中。下次執行「window」時,系統會先處理已緩衝的要求。另請參閱「新增緩衝區」。

高點逮捕人數是怎麼運作的?

您可以將尖峰時段逮捕做法視為一般預防流量高峰的方法,而非限制特定數量要求流量的方法。您的 API 和後端可以處理特定數量的流量,尖峰流量防範政策可協助您將流量順利分配至所需的一般金額。

執行階段尖峰期間的逮捕行為與您輸入的每分鐘或每秒常值不符。

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

spikearrest:
   timeUnit: minute
   allow: 30

在測試中,您可能會認為您可以在 1 秒內傳送 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 Micro 程序

允許的要求數量取決於正在執行的 Edge Micro 工作站程序數量。尖峰流量防範則會計算每個工作站程序允許的要求數量。根據預設,Edge Micro 程序的數量等於安裝 Edge Micro 的機器 CPU 數量。不過,您可以在啟動 Edge Micro 時,使用 start 指令中的 --processes 選項設定工作站程序數量。舉例來說,假設您想在指定時間範圍內的 100 個要求觸發高強度逮捕,而且您使用 --processes 4 選項啟動 Edge Microgateway,那麼請在高峰逮捕設定中設定 allow: 25。簡單來說,經驗法則是將 allow 設定參數設為「想要的尖峰逮捕計數 / 程序數量」值。

使用配額外掛程式

配額會指定應用程式在一個小時、一天、一週或一個月內可提交至 API 的要求訊息數量。當應用程式達到配額限制時,系統會拒絕後續的 API 呼叫。另請參閱尖峰流量逮捕與配額有何不同

新增配額外掛程式

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

Apigee Edge 中的產品設定

您可以在 Apigee Edge UI 中設定 API 產品的配額。您必須知道哪個產品包含您想設定配額限制的微閘道感知 Proxy。這項產品必須新增至開發人員應用程式。當您透過開發人員應用程式中的金鑰驗證 API 呼叫時,系統會將配額套用到這些 API 呼叫。

  1. 登入您的 Apigee Edge 機構帳戶。
  2. 在 Edge UI 中,開啟與要套用配額的微閘道感知 Proxy 相關聯的產品。
    1. 在使用者介面中,從「發布」選單中選取「產品」
    2. 開啟含有要套用配額的 API 的產品。
    3. 按一下「編輯」
    4. 在「Quota」(配額) 欄位中,指定配額間隔。例如,每分鐘 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 產品的配額間隔設為「分鐘」,Ecrogateway 每每 500 個要求或在 5 秒後 (兩者取其先) 就會與 Edge 保持同步,以便取得目前的配額數量。詳情請參閱瞭解配額的計算方式

允許的時間單位包括:minutehourdayweekmonthdefault

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 的配額為每小時 5,000 個
  • 產品 C 的配額為每月 100 萬個要求

瞭解這些配額設定之後,該如何設定 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 設為「月」間隔。每完成一個要求或經過 1 分鐘 (兩者取其先),Edge Microgateway 就會同步至 Edge。

每當微閘道執行個體與 Edge 同步時,微閘道的配額都會設為擷取到的配額計數。

您可以透過 bufferSize 設定調整配額計數器與 Edge 同步的方式。在高流量情況下,bufferSize 設定允許緩衝區計數器在觸發預設時間型同步處理作業之前進行同步處理。

瞭解配額範圍

配額數量的適用範圍是機構中的環境,為了達到這個範圍,Edge Microgateway 會建立配額 ID,並由「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 的要求訊息數量。配額政策會透過維護查詢傳入要求的分散式計數器,來強制執行用戶端應用程式的使用量限制。

透過配額政策,強制與開發人員和合作夥伴簽署商業合約或服務水準協議,而非管理營運流量。舉例來說,某項配額可能會用來限制免費服務的流量,同時讓付費客戶擁有完整存取權。

運用尖峰時段防範機制來防範 API 流量突然暴增。一般來說,高強度逮捕是為了抵禦分散式阻斷服務或其他惡意攻擊。