全部产品

配置参数映射模板

API 网关支持通过配置参数映射模板的方式对请求和响应数据进行自动化修改。本文将详细介绍参数映射模板的配置语法及注意事项等。

模板示例

  • 请求模板

    # 定义参数
    params:
        temp: $.Req.Header.temp
        body1: $.Req.Body.x
        body2: $.Req.Body.y
        bodyArray: $.Req.Body.y.z[0]
        body: $.Req.Body
    
    # 表达式,会返回一个值,用于 mapping
      expression: $.temp
    
    # 映射规则
      mappings:
    # 映射规则,至少一个
    ## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
        hello:
    # 执行下面的映射逻辑
    ## body 覆盖模板 (可选操作)
          bodyOverride:'[{"name": "{{ $.temp }}"}, {"temp": {{ $.body1}}}]'
    ## request header 设置,先执行 delete,再执行 add (可选操作)
          header:
            addKeyValue:
              ah: $.temp
            deleteKey:
    - temp
    ## request cookie 设置,先执行 delete,再执行 add (可选操作)
          cookie:
            addKeyValue:
              ac: $.temp
            deleteKey:
    - cookiekey
    ## request query 设置,先执行 delete,再执行 add (可选操作)
          query:
            addKeyValue:
              aq: $.temp
            deleteKey:
    - querykey
    中文:
    # 执行下面的映射逻辑
    ## body 覆盖模板 (可选操作)
          bodyOverride:|
    [
    {"name":{{ $.body1 }}},
    {"temp":{{ $.body2}}},
    {"array":{{$.bodyArray}}},
    {"body":{{$.body}}}
    ]
    
    # 默认映射规则
    default:
        bodyOverride:'{"name": "{{ $.temp }}"}'
        header:
          addKeyValue:
            ah: $.temp
          deleteKey:
    - temp
        cookie:
          addKeyValue:
            ac: $.temp
          deleteKey:
    - cookiekey
        query:
          addKeyValue:
            aq: $.temp
          deleteKey:
    - querykey
  • 响应模板

    # 定义参数
    params:
        temp: $.Resp.Header.temp
        bodyx: $.Resp.Body.x
        bodyy: $.Resp.Body.y
        bodyArray: $.Resp.Body.y.z[0]
        body: $.Resp.Body
    
    # 表达式,会返回一个值,用于 mapping
      expression: $.temp
    
    # 映射规则
      mappings:
    # 映射规则,至少一个
    ## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
        hello:
    # 执行下面的映射逻辑
    ## body 覆盖模板 (可选操作)
          bodyOverride:|
    [{"name":"{{ $.temp }}"},{"temp":{{ $.body1}}}]
    ## response header 设置,先执行 delete,再执行 add; (可选操作)
          header:
            addKeyValue:
              ah: $.temp
            deleteKey:
    - temp
        world:
    # 执行下面的映射逻辑
    ## body 覆盖模板; (可选操作)
          bodyOverride:|
    "xx"
    
    # 默认映射规则
    default:
        bodyOverride:|
    {"name":{{ $.temp }}}

如上示例所示,模板语法主要分为以下几个对象:

  • params:用于从请求或响应中提取参数。详见下文 params:提取参数

  • expression:一个表达式,该表达式会返回一个值。详见下文 expression:表达式

    • 如果表达式是一个判断表达式,则返回 true/false。

    • 如果表达式是一个字符串拼接,则返回一个字符串。

  • mappings:根据 expression 的返回内容,配置不同的映射规则。详见下文 mappings:映射规则

  • default:(可选操作),存储一个默认的映射规则。

params:提取参数

params 可以从 request 或者 response 中提取参数,格式为 k:v。其中 key 为自定义的参数名,value 是一个参数表达式,格式为:$.Type.Location.key

  • Type:可以是 Req 或者 Resp,分别表示请求和响应。

  • Location:可以是 Header、Query、Cookie 或者 Body。

    • Resp 只支持 Header 和 Body。

    • Body 必须为 JSON 格式。

示例

  • 示例 1:从请求 Header 中提取参数

    请求的 header:temp = headervalue
    定义:temp = $.Req.Header.temp
    结果:==> temp = headervalue
  • 示例 2:从请求 Cookie 中提取参数

    请求的 cookie:temp = cookievalue
    定义:temp = $.Req.Cookie.temp
    结果:==> temp = cookievalue
  • 示例 3:从请求 Body 中提取参数

    请求的 body:{"hello":{"world":["1","2","3"]}}
    定义:temp = $.Req.Body.hello.world[0]
    结果:==> temp =1
  • 示例 4:从响应 Body 中提取参数

    响应的 body:{"hello":{"world":["1","2","3"]}}
    定义:temp = $.Resp.Body.hello.world[0]
    结果:==> temp =1

expression:表达式

expression 表达式会返回一个值。表达式可以引用 params 中定义的变量,形式为 $.name

  • 示例 1

    请求的 body:{"hello":{"world":["1","2","3"]}}
    定义:temp = $.Req.Body.hello.world[0]
    表达式: $.temp ==1
    结果:true
  • 示例 2

    请求的 cookie:temp = cookievalue
    定义:temp = $.Req.Cookie.temp
    表达式: $.temp
    结果:cookievalue

mappings:映射规则

映射规则支持覆盖 Body、修改 Header、Query 和 Cookie。其中 Response 只支持修改 Body 和 Header。

覆盖 Body

bodyOverride 即覆盖 Body。值是 Go template 标准模板,可以通过 $.name 引用 params 中定义的变量。示例如下:

请求的 body:{"hello":{"world":["1","2","3"]}}
定义:temp = $.Req.Body.hello.world[0]
bodyOverride:'{"name": "{{ $.temp }}"}'
结果:{"name":"1"}

其中,bodyOverride 是一个字符串模板,所以要用前后要加一个单引号。示例如下:

# 只能放在同一行,不能换行
bodyOverride:'{"name": "{{ $.name }}" }'

如果 bodyOverride 很长,一行放不下,可以使用以下方式多行输入。示例如下:

# 在 bodyOverride 后加一个 |,即可多行输入
# 换行输入要空两格,符合 yaml 标准语法
bodyOverride:|
[
{"name":{{ $.body1 }}},
{"temp":{{ $.body2}}},
{"array":{{$.bodyArray}}},
{"body":{{$.body}}}
]

bodyOverride 的内容是一个 JSON 模板,要保证渲染后的结果是一个 JSON 字符串。

  • 如果引用的参数变量是 String 类型,则需要使用 "",如: {"name": "{{ $.string }}" }

  • 如果引用是参数变量是其他类型,则不需要 "",如: {"name": {{ $.object }} }

因此,配置模板时,必须确认参数的类型。示例如下:

假设 param.str ="jack"
定义 bodyOverride:'{"name": "{{ $.str }}" }'
渲染结果:{"name":"jack"}
------------
假设 param.obj ={"firstName":"tom"}
定义 bodyOverride:'{"name": {{ $.obj }} }'
渲染结果:{"name":{"firstName":"tom"}}

修改 Query、Header、Cookie

这三个 key 均可以定义 addKeyValue 和 deleteKey。

  • addKeyValue:kv 结构,会在相应位置添加对应的 kv,通过 $.name 引用 params 中定义的变量。

  • deleteKey:list,会将定义的所有 key 从相应位置删除。

执行时,会先执行删除操作,再执行添加操作。示例如下:

请求的 cookie:temp = cookievalue
定义:temp = $.Req.Cookie.temp
映射:cookie:
        addKeyValue:
            newkey: $.temp
        deleteKey:
-    temp
结果:cookie: newkey = cookievalue