Request Transformer 请求变更插件

https://docs.konghq.com/hub/kong-inc/request-transformer/

在上游服务器接收之前，变更客户端在Kong上发送的请求。

注意：此插件的功能与0.10.0之前的Kong版本捆绑在一起，与此处记录的不同。有关详细信息，请参阅CHANGELOG。

术语

  • plugin: 在请求被代理到上游API之前或之后，在Kong内部执行操作的插件。
  • Service: 表示外部 upstream API或微服务的Kong实体。
  • Route: 表示将下游请求映射到上游服务的方法的Kong实体。
  • Consumer: 代表使用API的开发人员或机器的Kong实体。当使用Kong时，Consumer 仅与Kong通信，其代理对所述上游API的每次调用。
  • Credential: 与Consumer关联的唯一字符串，也称为API密钥。
  • upstream service: 这是指位于Kong后面的您自己的 API/service，转发客户端请求。

配置

此插件与具有以下协议的请求兼容：

  • http
  • https

此插件与无DB模式兼容。

在 Service 上启用插件

使用数据库：

通过发出以下请求在Service上配置此插件：

  1. $ curl -X POST http://kong:8001/services/{service}/plugins \
  2.     --data "name=request-transformer"  \
  3.     --data "config.remove.headers=x-toremove" \
  4.     --data "config.remove.headers=x-another-one" \
  5.     --data "config.remove.querystring=qs-old-name:qs-new-name" \
  6.     --data "config.remove.querystring=qs2-old-name:qs2-new-name" \
  7.     --data "config.remove.body=formparam-toremove" \
  8.     --data "config.remove.body=formparam-another-one" \
  9.     --data "config.rename.headers=header-old-name:header-new-name" \
  10.     --data "config.rename.headers=another-old-name:another-new-name" \
  11.     --data "config.rename.querystring=qs-old-name:qs-new-name" \
  12.     --data "config.rename.querystring=qs2-old-name:qs2-new-name" \
  13.     --data "config.rename.body=param-old:param-new" \
  14.     --data "config.rename.body=param2-old:param2-new" \
  15.     --data "config.append.headers=x-existing-header:some_value" \
  16.     --data "config.append.headers=x-another-header:some_value" \
  17.     --data "config.add.headers=x-new-header:value" \
  18.     --data "config.add.headers=x-another-header:something" \
  19.     --data "config.add.querystring=new-param:some_value" \
  20.     --data "config.add.querystring=another-param:some_value" \
  21.     --data "config.add.body=new-form-param:some_value" \
  22.     --data "config.add.body=another-form-param:some_value"

不使用数据库：

通过添加此部分在服务上配置此插件执行声明性配置文件：

  1. plugins:
  2. - name: request-transformer
  3.   service: {service}
  4.   config: 
  5.     remove.headers:
  6.     - x-toremove
  7.     - x-another-one
  8.     remove.querystring:
  9.     - qs-old-name:qs-new-name
  10.     - qs2-old-name:qs2-new-name
  11.     remove.body:
  12.     - formparam-toremove
  13.     - formparam-another-one
  14.     rename.headers:
  15.     - header-old-name:header-new-name
  16.     - another-old-name:another-new-name
  17.     rename.querystring:
  18.     - qs-old-name:qs-new-name
  19.     - qs2-old-name:qs2-new-name
  20.     rename.body:
  21.     - param-old:param-new
  22.     - param2-old:param2-new
  23.     append.headers:
  24.     - x-existing-header:some_value
  25.     - x-another-header:some_value
  26.     add.headers:
  27.     - x-new-header:value
  28.     - x-another-header:something
  29.     add.querystring:
  30.     - new-param:some_value
  31.     - another-param:some_value
  32.     add.body:
  33.     - new-form-param:some_value
  34.     - another-form-param:some_value

在这两种情况下，{service}是此插件配置将定位的Route的ID或名称。

在 Consumer 上启用插件

使用数据库：

您可以使用http://localhost:8001/plugins在特定的Consumers上启用此插件:

  1. $ curl -X POST http://kong:8001/consumers/{consumer}/plugins \
  2.     --data "name=request-transformer" \
  3.      \
  4.     --data "config.remove.headers=x-toremove" \
  5.     --data "config.remove.headers=x-another-one" \
  6.     --data "config.remove.querystring=qs-old-name:qs-new-name" \
  7.     --data "config.remove.querystring=qs2-old-name:qs2-new-name" \
  8.     --data "config.remove.body=formparam-toremove" \
  9.     --data "config.remove.body=formparam-another-one" \
  10.     --data "config.rename.headers=header-old-name:header-new-name" \
  11.     --data "config.rename.headers=another-old-name:another-new-name" \
  12.     --data "config.rename.querystring=qs-old-name:qs-new-name" \
  13.     --data "config.rename.querystring=qs2-old-name:qs2-new-name" \
  14.     --data "config.rename.body=param-old:param-new" \
  15.     --data "config.rename.body=param2-old:param2-new" \
  16.     --data "config.append.headers=x-existing-header:some_value" \
  17.     --data "config.append.headers=x-another-header:some_value" \
  18.     --data "config.add.headers=x-new-header:value" \
  19.     --data "config.add.headers=x-another-header:something" \
  20.     --data "config.add.querystring=new-param:some_value" \
  21.     --data "config.add.querystring=another-param:some_value" \
  22.     --data "config.add.body=new-form-param:some_value" \
  23.     --data "config.add.body=another-form-param:some_value"

不使用数据库：

通过添加此部分在Consumer上配置此插件执行声明性配置文件：

  1. plugins:
  2. - name: request-transformer
  3.   consumer: {consumer}
  4.   config: 
  5.     remove.headers:
  6.     - x-toremove
  7.     - x-another-one
  8.     remove.querystring:
  9.     - qs-old-name:qs-new-name
  10.     - qs2-old-name:qs2-new-name
  11.     remove.body:
  12.     - formparam-toremove
  13.     - formparam-another-one
  14.     rename.headers:
  15.     - header-old-name:header-new-name
  16.     - another-old-name:another-new-name
  17.     rename.querystring:
  18.     - qs-old-name:qs-new-name
  19.     - qs2-old-name:qs2-new-name
  20.     rename.body:
  21.     - param-old:param-new
  22.     - param2-old:param2-new
  23.     append.headers:
  24.     - x-existing-header:some_value
  25.     - x-another-header:some_value
  26.     add.headers:
  27.     - x-new-header:value
  28.     - x-another-header:something
  29.     add.querystring:
  30.     - new-param:some_value
  31.     - another-param:some_value
  32.     add.body:
  33.     - new-form-param:some_value
  34.     - another-form-param:some_value

在这两种情况下，{consumer}都是此插件配置将定位的Consumer的id或username。
您可以组合consumer_id和service_id 。 在同一个请求中，进一步缩小插件的范围。

全局插件

  • 使用数据库： 可以使用http://kong:8001/plugins/配置所有插件。
  • 不使用数据库： 可以通过plugins: 配置所有插件：声明性配置文件中的条目。

与任何 Service ，Route 或 Consumer （或API，如果您使用旧版本的Kong）无关的插件被视为“全局”，并将在每个请求上运行。有关更多信息，请阅读插件参考和插件优先级部分。

参数

以下是可在此插件配置中使用的所有参数的列表：

参数 默认值 描述
name 要使用的插件的名称，在本例中为ip-restriction
service_id 此插件将定位的 Service 的ID。
route_id 此插件将定位的 Route 的ID。
enabled true 是否将应用此插件。
consumer_id 此插件将定位的Consumer的id
config.http_method
optional		 更改上游请求的HTTP方法。
config.remove.headers
optional		 headers 名列表。使用给定名称取消设置 header。
config.remove.querystring
optional		 查询字符串名称列表。删除查询字符串（如果存在）。
config.remove.body
optional		 参数名称列表。当且仅当content-type是以下[application/json，multipart/form-data，application/x-www-form-urlencoded]并且参数存在时，删除参数。
config.replace.headers
optional		 headername列表：键值对。当且仅当header已设置时，将其旧值替换为新值。如果尚未设置header，则忽略。
config.replace.querystring
optional		 查询名称列表：键值对。当且仅当字段名称已设置时，将其旧值替换为新值。如果尚未设置字段名称，则忽略。
config.rename.headers
optional		 headername列表：键值对。当且仅当标头已设置时，重命名header。该值保持不变。如果尚未设置标头，则忽略。
config.rename.querystring
optional		 查询名称列表：键值对。当且仅当已设置字段名称时，重命名字段名称。该值保持不变。如果尚未设置字段名称，则忽略。
config.rename.body
optional		 参数名称列表：键值对。当且仅当content-type为以下[application/json，multipart/form-data，application/x-www-form-urlencoded]且参数存在时，重命名参数名称。
config.append.headers
optional		 headername列表：键值对。如果未设置header，请使用给定值进行设置。如果已设置，则将设置具有相同名称和新值的新header。
config.replace.body
optional		 参数名称列表：键值对。当且仅当content-type是以下[application/json，multipart/form-data，application/x-www-form-urlencoded]并且参数已经存在时，将其旧值替换为新值。如果参数尚不存在，则忽略。
config.add.headers
optional		 headername列表：键值对。当且仅当header尚未设置时，设置具有给定值的新标头。如果已设置header，则忽略。
config.add.querystring
optional		 查询名称列表：键值对。当且仅当尚未设置查询字符串时，设置具有给定值的新查询字符串。如果已设置查询字符串，则忽略。
config.add.body
optional		 pramname列表：键值对。当且仅当内容类型是以下[application/json，multipart/form-data，application/x-www-form-urlencoded]并且参数不存在时，添加具有给定值的新参数以形成 form-encoded 请求体。如果参数已存在，则忽略。
config.append.headers
optional		 headername列表：键值对。如果未设置header，请使用给定值进行设置。如果已设置，则将附加具有相同名称和新值的其他新header。
config.append.querystring
optional		 查询名称列表：键值对。如果未设置查询字符串，请使用给定值进行设置。如果已设置，将设置具有相同名称和新值的新查询字符串。
config.append.body
optional		 参数名称列表：键值对。如果content-type是以下[application/json，multipart/form-data，application/x-www-form-urlencoded]中的一个，则在参数不存在的情况下添加具有给定值的新参数，否则如果它已经存在，则添加两个值（旧的和新的）将聚合在一个数组中。

注意：如果值包含一个,则不能使用以逗号分隔的列表格式。必须使用数组表示法。

基于请求内容的动态变更

与Kong Enterprise捆绑在一起的Request Transformer插件允许根据客户端请求中找到的变量数据添加或替换上游请求中的内容，例如请求header，查询字符串参数或URI捕获组定义的URI参数。

如果您已经是Kong Enterprise客户，则可以使用Enterprise支持渠道打开支持服务单，请求访问此插件功能。

如果您不是Kong Enterprise客户，可以通过联系我们来咨询我们的企业产品。

执行顺序

插件按以下顺序执行响应变更：
删除 -> 重命名 -> 替换 -> 添加 ->追加
remove –> rename –> replace –> add –> append

例子

在这些示例中，我们在服务上启用了插件。这对于Routes来说同样适用。

  • 通过分别传递每个header：键值对来添加多个header：

使用数据库：

  1. $ curl -X POST http://localhost:8001/services/example-service/plugins \
  2.   --data "name=request-transformer" \
  3.   --data "config.add.headers[1]=h1:v1" \
  4.   --data "config.add.headers[2]=h2:v1"

不使用数据库：

  1. plugins:
  2. - name: request-transformer
  3.   config:
  4.     add:
  5.       headers: ["h1:v1", "h2:v1"]
传入请求header 上游代理的 header
h1: v1 h1: v1
h2: v1
  • 通过传递逗号分隔的标头：值对来添加多个标头（仅适用于数据库）：
  1. $ curl -X POST http://localhost:8001/services/example-service/plugins \
  2.   --data "name=request-transformer" \
  3.   --data "config.add.headers=h1:v1,h2:v2"
传入请求header 上游代理的 header
h1: v1 h1: v1
h2: v1
  • 添加多个标头，将config作为JSON主体传递（仅适用于数据库）：
    1. $ curl -X POST http://localhost:8001/services/example-service/plugins \
    2. --header 'content-type: application/json' \
    3. --data '{"name": "request-transformer", "config": {"add": {"headers": ["h1:v2", "h2:v1"]}}}'
传入请求header 上游代理的 header
h1: v1 h1: v1
h2: v1
  • 添加查询字符串和header：

使用数据库：

  1. $ curl -X POST http://localhost:8001/services/example-service/plugins \
  2.   --data "name=request-transformer" \
  3.   --data "config.add.querystring=q1:v2,q2:v1" \
  4.   --data "config.add.headers=h1:v1"

不使用数据库：

  1. plugins:
  2. - name: request-transformer
  3.   config:
  4.     add:
  5.       headers: ["h1:v1"],
  6.       querystring: ["q1:v1", "q2:v2"]
传入请求header 上游代理的 header
h1: v2 h1: v2
h2: v1
h3: v1 h1: v1
h2: v1
h3: v1
传入请求查询字符串 上游代理的查询字符串
?q1=v1 ?q1=v1&q2=v1
?q1=v2&q2=v1
  • 附加多个标头并删除body参数：

使用数据库：

  1. $ curl -X POST http://localhost:8001/services/example-service/plugins \
  2.   --header 'content-type: application/json' \
  3.   --data '{"name": "request-transformer", "config": {"append": {"headers": ["h1:v2", "h2:v1"]}, "remove": {"body": ["p1"]}}}'

不使用数据库：

  1. plugins:
  2. - name: request-transformer
  3.   config:
  4.     add:
  5.       headers: ["h1:v1", "h2:v1"]
  6.     remove:
  7.       body: [ "p1" ]
传入请求header 上游代理的 header
h1: v1 h1: v1
h2: v1
传入请求查询字符串 上游代理的查询字符串
p1=v1&p2=v1 p2=v1
p2=v1 p2=v1