AI 助理
文档备案控制台
官方文档
首页

HTTP API方式

更新时间：
复制 MD 格式
产品详情
我的收藏

集成流目前支持HTTP请求和返回的同步调用方式触发。该方式在集成流中以HTTP API Listener和HTTP API Reply两个节点的形式表示。在创建集成流时，平台会根据创建时选择的触发方式类型在流中自动创建这两个节点。头尾的两个节点不可删除、不可移动，支持修改内容。

HTTP API Listener

概述

开发过程中：主要用于描述集成流和集成接口之间的绑定关系。集成流和集成接口之间的关系，请参见集成流与集成接口的关系说明。

在集成流编辑器中，流的头部为HTTP API Listener节点，尾部为HTTP API Reply节点。HTTP API Listener节点的配置面板中，监听的集成接口区域以表格形式展示已绑定的接口信息，包括接口分组、接口名称、HTTP Path和HTTP Method。

运行时：主要负责路由和入参校验，将校验通过的请求转换成相应的消息格式并向后续节点传递。

路由和入参校验

引擎在运行时会根据请求的HTTP Request Method和HTTP Requst URL进行匹配，查找对应的元数据进行动态处理。

同时，引擎还会根据集成接口定义的入参，对HTTP请求内容进行校验，只有满足条件的请求才能响应执行。如果校验失败，会直接返回错误。

  • 一次请求中同时出现多个校验失败错误时，只会选择报出其中一个错误信息。

  • 错误码信息如下。

错误代码

HTTP状态码

Message

描述

I400IP

400

Invalid parameter `${ParameterName}`

HTTP请求校验失败

示例如下：

  • 集成接口的定义如下，并已经完成与集成流的绑定。

该集成接口名称为http-listener-reply，接入路径为POST /group3/t1，已注册网关并开启默认认证。请求参数Query包含：q2（String类型，必填）和q1（Integer类型）。请求参数Body为application/json格式，定义了human对象，包含name（String类型）和age（Integer类型）两个字段。

  • 使用curl调用该集成接口，模拟Query参数的类型错误（对应本例中的q1参数）。

C:\>curl -i -X POST "http://xxx/group3/t1?q1=aaa&q2=111"
HTTP/1.1 400 Bad Request
Date: Mon, 25 Mar 2024 08:11:27 GMT
Content-Type: application/oct-stream
Content-Length: 0
Connection: keep-alive
x-bw-trace-id: F92C918D-9F74-426E-8C8B-472B2B6F9211
X-Bwiaf-Error-Message: Invalid parameter `Instance type (string) does not match any allowed primitive type (allowed: ["integer"])`
X-Ca-Request-Id: D022508E-6B93-4CE6-B148-7DEFE1D44031
X-Bwiaf-Error-Code: I400IP

  • 使用curl调用该集成接口，模拟Body错误（对应本例中不满足对象的JSON Schema定义）。

C:\>curl -i -H "Content-Type:application/json" -X POST -d "{\"name\":\"aa\",\"age\":\"bbb\"}" "http://xxx/group3/t1?q1=111&q2=111"
HTTP/1.1 400 Bad Request
Date: Mon, 25 Mar 2024 08:09:27 GMT
Content-Type: application/oct-stream
Content-Length: 0
Connection: keep-alive
x-bw-trace-id: 1632EB9B-8139-41C8-85E7-4D2037D81351
X-Bwiaf-Error-Message: Invalid parameter `[Path '/age'] Instance type (string) does not match any allowed primitive type (allowed: ["integer"])`
X-Ca-Request-Id: 9ADB4AC2-9300-485B-B90D-D0E37E37BE6D
X-Bwiaf-Error-Code: I400IP

节点输出消息

输出消息的Payload为HttpRequest类型，关于HttpRequest类型说明，请参见HttpRequest。

本文以获取调用集成接口的入参内容为例说明，具体如下。

  • 集成接口的定义如下，并完成与集成流的绑定。

该集成接口名称为http-listener-reply-2，接入路径为GET /group3/t2，已注册网关并开启默认认证，绑定服务为http-listener-reply。请求参数Query包含q1（String类型）。

  • 集成流中，将请求参数q1保存到消息的变量字段中，设置变量的节点配置如下：

在集成流中添加设置变量节点，位于HTTP API Listener与HTTP API Reply之间。节点配置中，添加变量varQ1，类型为String，值的获取方式选择脚本。

  • 对应的脚本内容如下，可获取到了接口的入参q1的值。

package bwiflu6pwj543473k0;

import com.alibaba.bwif.script.core.StepMessage
import com.alibaba.bwif.script.core.BwifHandler
import com.alibaba.bwif.script.core.protocol.http.HttpRequest
import com.alibaba.bwif.script.core.Entity

class SimpleHandler implements BwifHandler {
    @Override
    Object handle(StepMessage message) {
        HttpRequest req = message.getPayload()
        String q1 = req.getQueryParam("q1")
        return q1
    }
}

HTTP API Reply

概述

您可以在本节点中定义调用集成接口获得的HTTP Response的内容。

节点配置

主要的节点配置信息为HTTP响应信息（Response），相关配置项详细说明如下：

配置项

说明

HTTP Status Code

  • 必填。

  • 支持固定值和脚本两种方式配置。

  • 使用脚本配置时，需要返回Integer类型。

Body

  • 非必填。

  • 支持固定值和脚本两种方式配置。

  • Content-Type目前仅支持application/json类型。

  • 使用脚本配置时，需要返回Entity类型。

Header

  • 非必填。

  • 支持固定值和脚本两种方式配置。

  • 固定值方式下可添加多行，每行为key-value结构。

  • 使用脚本配置时，需要返回HashMap<String, String>结构。

Cookie

为Cookie单独提供的配置，运行时会合并到Response Header中。Cookie相关的操作建议优先在Cookie页签下操作。如果同时在Header页签中配置了“Set-Cookie”，则引擎在处理时不会对Set-Cookie内容进行合并，而是作为多条重复Header方式返回。

  • 非必填。

  • 支持固定值和脚本两种方式配置。

  • 固定值方式下可添加多行，每行为key-value结构。

  • 使用脚本配置时，需要返回HashMap<String, String>结构。
说明

HTTP响应信息和此集成流绑定的集成接口定义没有直接关系，需要开发者根据接口定义完成返回内容的设计。

使用示例

动态生成Entity对象，作为HTTP Response body的内容。具体示例请参见快速入门HTTP API Reply。

默认Response结构

引擎默认对返回的HTTP Response结构有统一约定，具体如下：

  • Body部分。由开发者指定，通过HTTP API Reply节点中配置而来。

  • Header部分。引擎默认会增加如下信息，用于方便排查问题。

Header Key

举例

说明

X-Ca-Request-Id

F21D0412-65A4-4312-9305-60C112D019AE

集成接口会发布到API网关上，此ID为网关自动生成，标识每次请求。

X-Bw-Trace-Id

3F0C6F80-AD22-4427-9151-3D7B1FDAD29D

集成流引擎生成的TraceID，标识此次调用的唯一ID。

X-Bwiaf-Error-Code

X500ER

集成流引擎返回的错误码，只有报错时会出现。

X-Bwiaf-Error-Message

Service Internal Error

集成流引擎返回的错误码补充描述，只有报错时会出现。
上一篇：触发方式下一篇：脚本