什麼是外掛程式資料集,如何配置外掛程式資料集 - API Gateway

API Gateway為使用者提供了功能強大、支援熱更新外掛程式體系，大量核心能力均被遷移到外掛程式體系中，截止目前為止API Gateway已經為使用者提供了12種外掛程式。外掛程式功能的上線極大豐富了API Gateway為使用者提供服務的功能點，也很大程度提升了API Gateway中繼資料管理的靈活性。但在一些大型業務情境，API Gateway的文本外掛程式對使用者的業務起到了限制作用，因此我們將外掛程式中的配置資料抽象成資料集對象進行單獨管理，大幅提升了外掛程式體系的使用體驗和擴充能力。

1. 文本外掛程式的局限性

API Gateway的外掛程式有一些特性：

純文字配置；
文本外掛程式大小有限制；

由於以上兩條限制，使用者在使用API Gateway的部分外掛程式時會感到非常不便，甚至某些功能無法使用。我們舉個例子，IP存取控制外掛程式是使用者用得比較多的外掛程式，下面是一個典型的IP存取控制的外掛程式配置：

---
type: ALLOW 
items: 
- blocks:
  - 61.3.XX.XX/24
  - 192.168.34.XX/32
  - 192.168.158.XX/32
  appId: 219810
- blocks:
  - 79.11.XX.XX
  - 85.13.XX.XX
  - 72.152.XX.XX

如果小型應用只有幾個網段，這個配置看起來沒有太大的問題。如果在大型的應用後端，有幾十個上百個網段需要配置到IP存取控制外掛程式中，使用者就會遇到兩個問題：

文本管理太容易出錯，修改一個IP段，需要全量更新整個外掛程式
IP段太多會導致外掛程式文本超限

上面兩個問題在目前基於文本配置的外掛程式體系是無法解決的。我們這次為使用者帶來了外掛程式資料集功能可以完美解決以上兩個問題。

2. 資料配置抽象成外掛程式資料集對象

下面我們來介紹下外掛程式資料集功能，簡單說就是把外掛程式中需要用到資料配置的地方抽象成單獨的資料集對象，然後在外掛程式中引用資料集對象。對資料集對象的修改會對所有引用了此資料集對象的外掛程式即時生效。

還是上面那個IP存取控制外掛程式舉例，使用資料外掛程式集之後可以簡單配置成

---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3

後續這個IP存取控制的外掛程式可以不用修改，僅修改定義中的兩個外掛程式資料集內的資料條目即可。

使用了資料集的外掛程式輕鬆解決上面說的兩個問題：

API Gateway把外掛程式中用到的配置資料抽象成資料集之後，資料集可以儲存資料的大小是彈性的，可以完美解決外掛程式大小限制業務需求的情況；
使用者可以通過局部修改資料集來實現修改外掛程式具備配置的效果，比如IP白名單中新增一個IP，只需要在資料集中新加一條資料就好了，不需要修改整個外掛程式；

API Gateway目前在JWT認證外掛程式中支援了外掛程式資料集的使用，後續會在IP存取控制、參數存取控制、後端路由等外掛程式中均支援外掛程式資料集能力。

3. 外掛程式資料集的特性

API Gateway提供的外掛程式資料集方便使用者動態修改外掛程式中的配置資料，外掛程式資料集具體具備以下特性：

資料集內配置資料條目，十秒內在使用者所有的專享執行個體上生效；
允許使用者定義100個資料集，每個資料集允許添加200條資料；如果使用者業務上不夠用，使用者可以提工單，API Gateway可以根據使用者的實際業務情境為使用者增加限制；
同一個資料集允許被多個外掛程式引用，資料集修改後所有引用了資料集的外掛程式同時生效；
資料集內資料不允許重複；
允許使用者佈建資料集內單條資料的到期時間，單條資料到期後將自動失效，允許設定不到期；
僅專享執行個體上的分組有效，分組一旦遷移到共用執行個體/Serverless執行個體，資料集馬上失效；

4. JWT認證外掛程式使用外掛程式資料集的具體配置方法

4.1.外掛程式資料集配置

建立資料集

需要給資料集設定一個名稱，並且選定資料集的類型。資料集的名稱可以任意修改，但類型一旦選定就不能再修改。JWT認證外掛程式選擇“JWT_BLOCKING”類型。

在外掛程式資料集中建立資料條目

點擊進入一個外掛程式資料集，可以在資料集下建立資料條目。資料條目的資料值在整個資料集內需要保持唯一。可以為每個資料條目設定到期時間，設定了到期時間的到期條目在到期後會自動失效。

2022-10-17 at 16.08.png

擷取外掛程式資料集的ID

外掛程式Data Integration功建立後，可以在資料集列表頁面看到這個資料集的ID，這個ID是聯絡外掛程式和外掛程式資料集的關鍵字段，這個ID是不會變化的。

2022-10-17 at 16.18.png

4.2.JWT認證外掛程式配置

目前API Gateway的JWT認證外掛程式已經整合了資料集的能力。

JWT認證外掛程式的使用情境有一個典型的需求就是屏蔽已經獲得了正式Token，但被拉到黑名單的使用者請求。API Gateway的JWT認證外掛程式為這種情境結合外掛程式資料集的能力上線了根據Token中解密出來的claim參數進行拒絕請求的能力。API Gateway不僅能夠拒絕命中了Blocking條件的請求，還能自訂拒絕的應答。具體的配置方法如下，請注意所有以block開頭的參數定義：

---
parameter: Authorization   # 從Authorization頭中擷取Token 
parameterLocation: header  # 從Authorization頭中擷取Token
claimParameters:           # claims參數轉換, 網關會將jwt claims映射為後端參數
- claimName: aud           # claim名稱,支援公用和私人
  parameterName: X-Aud     # 映射後參數名稱
  location: header         # 映射後參數位置, 支援`query,header,path,formData`
- claimName: userId        # claim名稱,支援公用和私人
  parameterName: userId    # 映射後參數名稱
  location: query          # 映射後的參數位置, 支援`query,header,path,formData`
blockClaimParameterName: userId  # 映射後的參數位置, 支援`query,header,path,formData`
blockByDataSet: 87b65008e92541938537b1a4a236eda5  # 映射後的參數位置, 支援`query,header,path,formData`
blockStatusCode: 403       # 拒絕請求返回的應答StatusCode定義
blockResponseHeaders:      # 拒絕請求返回的應答頭定義
  Content-Type: application/xml
blockResponseBody:         # 拒絕請求返回的Body定義
  <Reason>be blocked</Reason>
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz         # 配置多個JWK時，需要使用不同的`kid`
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....

5. 小結

API Gateway外掛程式體系增加了外掛程式資料集的功能後，從文本時代走向了結構化資料的時代，外掛程式中用到的資料支援局部熱更新，並且在資料量層級的限制上提升了一個台階。針對一些大使用者的業務情境，我們可以支援到百萬層級的外掛程式資料集，使用者不再在外掛程式上收到資料量大小的限制，徹底開啟使用者使用API Gateway外掛程式的想象力。

目前外掛程式資料集剛上線，API Gateway僅將外掛程式資料集整合到了JWT認證外掛程式中，後續會陸續在IP存取控制、參數存取控制、後端路由等外掛程式中均支援外掛程式資料集能力。