全部产品
Search

搜索本产品

    API 网关：插件数据集

    文档中心

    API 网关：插件数据集

    更新时间：Oct 25, 2024

    API网关为用户提供了功能强大、支持热更新插件体系，大量核心能力均被迁移到插件体系中，截止目前为止API网关已经为用户提供了12种插件。插件功能的上线极大丰富了API网关为用户提供服务的功能点，也很大程度提升了API网关元数据管理的灵活性。但在一些大型业务场景，API网关的文本插件对用户的业务起到了限制作用，因此我们将插件中的配置数据抽象成数据集对象进行单独管理，大幅提升了插件体系的使用体验和扩展能力。

    1. 文本插件的局限性

    API网关的插件有一些特性：

    • 纯文本配置；

    • 文本插件大小有限制；

    由于以上两条限制，用户在使用API网关的部分插件时会感到非常不便，甚至某些功能无法使用。我们举个例子，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. 数据配置抽象成插件数据集对象

    下面我们来介绍下插件数据集功能，简单说就是把插件中需要用到数据配置的地方抽象成单独的数据集对象，然后在插件中引用数据集对象。对数据集对象的修改会对所有引用了此数据集对象的插件实时生效。

    image

    还是上面那个IP访问控制插件举例，使用数据插件集之后可以简单配置成

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

    后续这个IP访问控制的插件可以不用修改，仅修改定义中的两个插件数据集内的数据条目即可。

    使用了数据集的插件轻松解决上面说的两个问题：

    • API网关把插件中用到的配置数据抽象成数据集之后，数据集可以保存数据的大小是弹性的，可以完美解决插件大小限制业务需求的情况；

    • 用户可以通过局部修改数据集来实现修改插件具备配置的效果，比如IP白名单中新增一个IP，只需要在数据集中新加一条数据就好了，不需要修改整个插件；

    API网关目前在JWT认证插件中支持了插件数据集的使用，后续会在IP访问控制、参数访问控制、后端路由等插件中均支持插件数据集能力。

    3. 插件数据集的特性

    API网关提供的插件数据集方便用户动态修改插件中的配置数据，插件数据集具体具备以下特性：

    1. 数据集内配置数据条目，十秒内在用户所有的专享实例上生效；

    2. 允许用户定义100个数据集，每个数据集允许添加200条数据；如果用户业务上不够用，用户可以提工单，API网关可以根据用户的实际业务场景为用户增加限制；

    3. 同一个数据集允许被多个插件引用，数据集修改后所有引用了数据集的插件同时生效；

    4. 数据集内数据不允许重复；

    5. 允许用户设置数据集内单条数据的过期时间，单条数据过期后将自动失效，允许设置不过期；

    6. 仅专享实例上的分组有效，分组一旦迁移到共享实例/Serverless实例，数据集马上失效；

    4. JWT认证插件使用插件数据集的具体配置方法

    4.1.插件数据集配置

    • 创建数据集

    需要给数据集设置一个名称，并且选定数据集的类型。数据集的名称可以任意修改，但类型一旦选定就不能再修改。JWT认证插件选择“JWT_BLOCKING”类型。

    • 在插件数据集中创建数据条目

    点击进入一个插件数据集，可以在数据集下创建数据条目。数据条目的数据值在整个数据集内需要保持唯一。可以为每个数据条目设置过期时间，设置了过期时间的过期条目在过期后会自动失效。

    2022-10-17 at 16.08.png

    • 获取插件数据集的ID

    插件数据集成功创建后，可以在数据集列表页面看到这个数据集的ID，这个ID是联系插件和插件数据集的关键字段，这个ID是不会变化的。

    2022-10-17 at 16.18.png

    4.2.JWT认证插件配置

    目前API网关的JWT认证插件已经集成了数据集的能力。

    JWT认证插件的使用场景有一个典型的需求就是屏蔽已经获得了正式Token，但被拉到黑名单的用户请求。API网关的JWT认证插件为这种场景结合插件数据集的能力上线了根据Token中解密出来的claim参数进行拒绝请求的能力。API网关不仅能够拒绝命中了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网关插件体系增加了插件数据集的功能后，从文本时代走向了结构化数据的时代，插件中用到的数据支持局部热更新，并且在数据量级别的限制上提升了一个台阶。针对一些大用户的业务场景，我们可以支持到百万级别的插件数据集，用户不再在插件上收到数据量大小的限制，彻底打开用户使用API网关插件的想象力。

    目前插件数据集刚上线，API网关仅将插件数据集集成到了JWT认证插件中，后续会陆续在IP访问控制、参数访问控制、后端路由等插件中均支持插件数据集能力。