文档

HTTP API方式

更新时间:

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

HTTP API Listener

概述

开发过程中:主要用于描述集成流和集成接口之间的绑定关系,如下图所示。集成流和集成接口之间的关系,请参见集成流与集成接口的关系说明

image.png

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

路由和入参校验

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

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

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

  • 错误码信息如下:

错误代码

HTTP状态码

Message

描述

I400IP

400

Invalid parameter `${ParameterName}`

HTTP请求校验失败

示例如下:

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

image.png

  • 使用curl调用该集成接口,模拟Query参数的类型错误(对应本例中的q1参数),如下图所示。

image.png

  • 使用curl调用该集成接口,模拟Body错误(对应本例中不满足对象的JSON Schema定义),如下图所示。

image.png

节点输出消息

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

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

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

image.png

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

image.png

  • 对应的脚本内容如下,可获取到了接口的入参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的内容。

节点配置

image

主要的节点配置信息为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

集成流引擎返回的错误码补充描述,只有报错时会出现。