全部产品

配置参数映射模板

更新时间:2020-07-21 14:29:30

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

模板示例

  • 请求模板

    1. # 定义参数
    2. params:
    3. temp: $.Req.Header.temp
    4. body1: $.Req.Body.x
    5. body2: $.Req.Body.y
    6. bodyArray: $.Req.Body.y.z[0]
    7. body: $.Req.Body
    8. # 表达式,会返回一个值,用于 mapping
    9. expression: $.temp
    10. # 映射规则
    11. mappings:
    12. # 映射规则,至少一个
    13. ## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
    14. hello:
    15. # 执行下面的映射逻辑
    16. ## body 覆盖模板 可选
    17. bodyOverride: '[{"name": "{{ $.temp }}"}, {"temp": {{ $.body1}}}]'
    18. ## request header 设置,先执行 delete,再执行 add 可选
    19. header:
    20. addKeyValue:
    21. ah: $.temp
    22. deleteKey:
    23. - temp
    24. ## request cookie 设置,先执行 delete,再执行 add 可选
    25. cookie:
    26. addKeyValue:
    27. ac: $.temp
    28. deleteKey:
    29. - cookiekey
    30. ## request query 设置,先执行 delete,再执行 add 可选
    31. query:
    32. addKeyValue:
    33. aq: $.temp
    34. deleteKey:
    35. - querykey
    36. 中文:
    37. # 执行下面的映射逻辑
    38. ## body 覆盖模板 可选
    39. bodyOverride: |
    40. [
    41. {"name": {{ $.body1 }}},
    42. {"temp": {{ $.body2}}},
    43. {"array":{{$.bodyArray}}},
    44. {"body": {{$.body}}}
    45. ]
    46. # 默认映射规则
    47. default:
    48. bodyOverride: '{"name": "{{ $.temp }}"}'
    49. header:
    50. addKeyValue:
    51. ah: $.temp
    52. deleteKey:
    53. - temp
    54. cookie:
    55. addKeyValue:
    56. ac: $.temp
    57. deleteKey:
    58. - cookiekey
    59. query:
    60. addKeyValue:
    61. aq: $.temp
    62. deleteKey:
    63. - querykey
  • 响应模板

    1. # 定义参数
    2. params:
    3. temp: $.Resp.Header.temp
    4. bodyx: $.Resp.Body.x
    5. bodyy: $.Resp.Body.y
    6. bodyArray: $.Resp.Body.y.z[0]
    7. body: $.Resp.Body
    8. # 表达式,会返回一个值,用于 mapping
    9. expression: $.temp
    10. # 映射规则
    11. mappings:
    12. # 映射规则,至少一个
    13. ## 如果 expression 返回了 hello, 也就是 header temp 的 value 是 hello
    14. hello:
    15. # 执行下面的映射逻辑
    16. ## body 覆盖模板 可选
    17. bodyOverride: |
    18. [{"name": "{{ $.temp }}"}, {"temp": {{ $.body1}}}]
    19. ## response header 设置,先执行 delete,再执行 add; 可选
    20. header:
    21. addKeyValue:
    22. ah: $.temp
    23. deleteKey:
    24. - temp
    25. world:
    26. # 执行下面的映射逻辑
    27. ## body 覆盖模板; 可选
    28. bodyOverride: |
    29. "xx"
    30. # 默认映射规则
    31. default:
    32. bodyOverride: |
    33. {"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 中提取参数
    1. 请求的 headertemp = headervalue
    2. 定义:temp = $.Req.Header.temp
    3. 结果:==> temp = headervalue
  • 示例 2:从请求 Cookie 中提取参数
    1. 请求的 cookietemp = cookievalue
    2. 定义:temp = $.Req.Cookie.temp
    3. 结果:==> temp = cookievalue
  • 示例 3:从请求 Body 中提取参数
    1. 请求的 body:{"hello": {"world": ["1","2","3"]}}
    2. 定义:temp = $.Req.Body.hello.world[0]
    3. 结果:==> temp = 1
  • 示例 4:从响应 Body 中提取参数
    1. 响应的 body:{"hello": {"world": ["1","2","3"]}}
    2. 定义:temp = $.Resp.Body.hello.world[0]
    3. 结果:==> temp = 1

expression:表达式

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

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

mappings:映射规则

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

覆盖 Body

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

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

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

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

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

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

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

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

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

  1. 假设 param.str = "jack"
  2. 定义 bodyOverride: '{"name": "{{ $.str }}" }'
  3. 渲染结果: {"name": "jack"}
  4. ------------
  5. 假设 param.obj = {"firstName":"tom"}
  6. 定义 bodyOverride: '{"name": {{ $.obj }} }'
  7. 渲染结果: {"name": {"firstName":"tom"}}

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

  • addKeyValue:kv 结构,会在相应位置添加对应的 kv,通过 $.name 引用 params 中定义的变量。
  • deleteKey:list,会将定义的所有 key 从相应位置删除。

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

  1. 请求的 cookietemp = cookievalue
  2. 定义:temp = $.Req.Cookie.temp
  3. 映射:cookie:
  4. addKeyValue:
  5. newkey: $.temp
  6. deleteKey:
  7. - temp
  8. 结果:cookie: newkey = cookievalue