batch-requests

描述

在启用 batch-requests 插件后,用户可以通过将多个请求组装成一个请求的形式,把请求发送给网关,网关会从请求体中解析出对应的请求,再分别封装成独立的请求,以 HTTP pipeline 的方式代替用户向网关自身再发起多个 HTTP 请求,经历路由匹配,转发到对应上游等多个阶段,合并结果后再返回客户端。

batch-request

在客户端需要访问多个 API 的情况下,这将显著提高性能。

batch-requests - 图2note

用户原始请求中的请求头(除了以 Content- 开始的请求头,例如:Content-Type)将被赋给 HTTP pipeline 中的每个请求,因此对于网关来说,这些以 HTTP pipeline 方式发送给自身的请求与用户直接发起的外部请求没有什么不同,只能访问已经配置好的路由,并将经历完整的鉴权过程,因此不存在安全问题。

如果原始请求的请求头与插件中配置的请求头冲突,则以插件中配置的请求头优先(配置文件中指定的 real_ip_header 除外)。

属性

无。

接口

该插件会增加 /apisix/batch-requests 接口。

batch-requests - 图3note

你需要通过 public-api 插件来暴露它。

启用插件

该插件默认是禁用状态,你可以在配置文件(./conf/config.yaml)添加如下配置启用 batch-requests 插件:

conf/config.yaml

  1. plugins:
  2. - ...
  3. - batch-requests

配置插件

默认情况下,可以发送到 /apisix/batch-requests 的最大请求体不能大于 1 MiB。你可以通过 apisix/admin/plugin_metadata/batch-requests 更改插件的此配置:

batch-requests - 图4note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量:

  1. admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
  1. curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/batch-requests \
  2. -H "X-API-KEY: $admin_key" -X PUT -d '
  3. {
  4. "max_body_size": 4194304
  5. }'

元数据

名称类型必选项默认值有效值描述
max_body_sizeinteger1048576[1, …]请求体的最大大小,单位:bytes。

请求和响应格式

该插件会为 apisix 创建一个 /apisix/batch-requests 的接口,用来处理批量请求。

请求参数

参数名类型必选项默认值描述
queryobject给所有请求都携带的 query string
headersobject给所有请求都携带的 header
timeoutnumber30000聚合请求的超时时间,单位为 ms
pipelinearray[HttpRequest]HTTP 请求的详细信息。

HttpRequest

参数名类型必选项默认值有效值描述
versionstring1.1[1.0, 1.1]请求所使用的 HTTP 协议版本。
methodstringGET[“GET”, “POST”, “PUT”, “DELETE”, “PATCH”, “HEAD”, “OPTIONS”, “CONNECT”, “TRACE”]请求使用的 HTTP 方法。
queryobject独立请求所携带的 query string, 如果 Key 和全局的有冲突,以此设置为主。
headersobject独立请求所携带的 header, 如果 Key 和全局的有冲突,以此设置为主。
pathstringHTTP 请求路径。
bodystringHTTP 请求体。
ssl_verifybooleanfalse验证 SSL 证书与主机名是否匹配。

响应参数

返回值是一个 HttpResponse数组

HttpResponse

参数名类型描述
statusintegerHTTP 请求的状态码。
reasonstringHTTP 请求的返回信息。
bodystringHTTP 请求的响应体。
headersobjectHTTP 请求的响应头。

修改自定义 URI

你可以通过 public-api 插件设置自定义 URI。

只需要在创建路由时设置所需的 URI 并更改 public-api 插件的配置:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/br \
  2. -H "X-API-KEY: $admin_key" -X PUT -d '
  3. {
  4. "uri": "/batch-requests",
  5. "plugins": {
  6. "public-api": {
  7. "uri": "/apisix/batch-requests"
  8. }
  9. }
  10. }'

测试插件

首先,你需要为 batch-requests 插件的 API 创建一个路由,它将使用 public-api 插件。

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H "X-API-KEY: $admin_key" -X PUT -d '
  3. {
  4. "uri": "/apisix/batch-requests",
  5. "plugins": {
  6. "public-api": {}
  7. }
  8. }'

之后,你就可以将要访问的请求信息传到网关的批量请求接口(/apisix/batch-requests)了,网关会以 http pipeline 的方式自动帮你完成请求。

  1. curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
  2. --header 'Content-Type: application/json' \
  3. --data '{
  4. "headers": {
  5. "Content-Type": "application/json",
  6. "admin-jwt":"xxxx"
  7. },
  8. "timeout": 500,
  9. "pipeline": [
  10. {
  11. "method": "POST",
  12. "path": "/community.GiftSrv/GetGifts",
  13. "body": "test"
  14. },
  15. {
  16. "method": "POST",
  17. "path": "/community.GiftSrv/GetGifts",
  18. "body": "test2"
  19. }
  20. ]
  21. }'

正常返回结果如下:

  1. [
  2. {
  3. "status": 200,
  4. "reason": "OK",
  5. "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
  6. "headers": {
  7. "Connection": "keep-alive",
  8. "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
  9. "Content-Type": "application/json",
  10. "Content-Length": "81",
  11. "Server": "APISIX web server"
  12. }
  13. },
  14. {
  15. "status": 200,
  16. "reason": "OK",
  17. "body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
  18. "headers": {
  19. "Connection": "keep-alive",
  20. "Date": "Sat, 11 Apr 2020 17:53:20 GMT",
  21. "Content-Type": "application/json",
  22. "Content-Length": "81",
  23. "Server": "APISIX web server"
  24. }
  25. }
  26. ]

删除插件

如果你想禁用插件,可以将 batch-requests 从配置文件中的插件列表删除,重新加载 APISIX 后即可生效。

conf/config.yaml

  1. plugins: # plugin list
  2. - ...