开发API工作流

数据服务API编排是指将已经开发好的服务API接口，在无需编写复杂代码的情况下，根据特定的业务逻辑和流程进行可视化的重组和重构，从而实现在不影响原生接口的前提下进行简便的二次开发。API编排为您提供拖拽式、可视化的API工作流程编排能力,您可以按照业务逻辑，以串行、并行等结构组合多个API为工作流，然后通过入口API调用API工作流，最终返回所需数据。

API编排使得业务流程的设计和优化变得更加直观和高效，同时也为二次开发提供了更便捷的方式。建议您在如下场景中可以使用API编排，简化开发工作：

对返回消息进行映射或格式转换：通过API编排的方式能够灵活实现消息映射及格式转换。
数据请求依赖多个数据API：使用API编排后，可以降低调用次数，减少集成成本，提升调用效率。

约束与限制

仅3.0.6及以上版本的数据服务专享版集群支持API编排。
API工作流发布前，需确保其中的普通API均已处于已发布状态。

算子和工作流简介

在API工作流编排页面，您可以自由拖拽各类算子到画布中，然后基于特定的业务逻辑和流程通过连线编排工作流，最后配置算子，完成后即可保存、调试及发布工作流。

API编排支持五类可拖拽的算子，分别为：入口API、普通API、条件分支、并行处理和输出处理。其中，入口API位于最上游，输出处理位于最下游，中间部分可以是普通API、条件分支和并行处理这三类算子的任意组合。注意，编排工作流时需要满足如下要求：

有且只有一个入口API算子，并位于最上游，向下只能有一个分支。
至少有一个普通API算子，并位于中间层，上下游均有其他算子，向下只能有一个分支。
条件分支算子可选，位于中间层，必须至少有2个分支，最多支持20个分支，多个分支满足条件时仅执行第一个满足条件的分支。
注意，条件分支的直接下游不能为输出处理算子，只能获取上级算子请求参数或结果集进行条件判断。
并行处理算子可选，位于中间层，必须至少有2个分支，最多支持20个分支，必须配置失败策略。
注意，并行处理的直接下游不能为输出处理算子，只能支持同时执行多个分支逻辑，分支间互不影响。
有且只有一个输出处理算子，并位于最下游，直接上游必须为普通API算子，必须配置至少一个结果映射。
API工作流不能有环状结构，不能有孤立算子，最多支持20层深度。

图1 API工作流编排页面
点击放大

表1 API工作流算子介绍
配置入口	算子	是否必选	介绍
触发器	入口API	必选	入口API算子是API工作流的入口，工作流发布后可通过调用入口API来调用API工作流。在入口API算子内需定义API工作流的名称、URL、参数协议、请求方式、审核人、安全认证以及请求参数。入口API算子的配置方法，详见入口API算子。
API目录	普通API	必选	普通API是执行数据查询操作的算子。普通API即已创建的数据API，编排API时您可以从API目录内拖拽一个普通API作为执行算子进行取数，并将请求参数或结果集作为变量传递下去。普通API可参考配置方式生成API或脚本/MyBatis方式生成API进行创建。
逻辑控制器	条件分支	非必选	条件分支算子通过获取上游算子的请求参数或结果集进行条件判断，根据定义的表达式来确定下一步执行的分支。注意，多个分支满足条件时仅执行第一个满足条件的分支。条件分支算子和表达式的配置方法，详见条件分支算子。
	并行处理	非必选	并行处理算子可以同时执行多个分支逻辑，分支间互不影响。并行处理算子的配置方法，详见并行处理算子。
	输出处理	必选	输出处理算子负责对API工作流的执行结果进行错误码映射、结果集映射和格式转换，以确定最终返回的数据格式。输出处理算子的配置方法，详见输出处理算子。

开发API工作流1：对返回消息进行映射或格式转换

某API默认返回的是JSON数据，现需要将API调用结果转换为EXCEL格式。

在DataArts Studio控制台首页，选择实例，单击“进入控制台”，选择对应工作空间的“数据服务”模块，进入数据服务页面。
图2 选择数据服务

在左侧导航栏选择服务版本（例如：专享版），进入总览页。
进入“开发API > > API编排”页面，单击新建，进入API编排页面。
图3 进入API编排页面
拖拽“入口API”算子到画布，单击画布上的算子打开配置面板，配置入口API信息。
图4 配置入口API算子
在API目录找到需要转换的普通API并拖拽到画布，挂载到入口API下。单击画布上的普通API打开配置面板，复制节点编码例如：NormalApi_5274d。
图5 复制节点编码
拖拽“输出处理”算子到画布，挂载到普通API下。单击画布上的输出处理算子打开配置面板，配置输出处理算子：
- 添加结果集映射。节点映射表达式取普通API的结果，如“${NormalApi_5274d|payload}”，结果集名称按照实际取值，此处以销售记录Sales records为例进行配置。
- 格式转换选择返回格式为EXCEL。
图6 配置输出处理算子
保存API工作量，然后调试并发布到集群。则后续调用者就可以通过调用API工作流中的入口API，实现普通API取数结果保存在EXCEL文件中。

开发API工作流2：数据请求依赖多个数据API

在电子商务平台的场景中，某部门需要根据用户所在地区的不同，提供不同的信息和服务：如果用户位于area1地区，系统将提供供应商信息Supplier Information和销售评级数据Sales Rating；如果用户位于其他地区，系统则会返回零售商信息Retailer Information。

当前已有地区信息API是AreaInformation、供应商信息API是SupplierInformation、销售评级API是SalesRating、零售商信息API是RetailerInformation，则您可以参考后续步骤进行API工作流编排。

在DataArts Studio控制台首页，选择实例，单击“进入控制台”，选择对应工作空间的“数据服务”模块，进入数据服务页面。
图7 选择数据服务

在左侧导航栏选择服务版本（例如：专享版），进入总览页。
进入“开发API > > API编排”页面，单击新建，进入API编排页面。
图8 进入API编排页面
拖拽“入口API”算子到画布，单击画布上的算子打开配置面板，配置入口API信息。
图9 配置入口API算子
在API目录找到地区信息AreaInformation API并拖拽到画布，挂载到入口API下。单击画布上的普通API打开配置面板，复制节点编码例如：NormalApi_ff8bd。
图10 复制AreaInformation节点编码
拖拽“条件分支”算子到画布，挂载到AreaInformation API下，并在条件分支下挂载并行处理算子和零售商信息RetailerInformation API两个分支。其中零售商信息RetailerInformation普通API的节点编码为NormalApi_de62d。
单击画布上的条件分支算子打开配置面板，配置条件分支算子：
- 并行处理分支的条件类型配置为“满足条件时”，表达式配置为“${NormalApi_ff8bd|payload.data[0].area}”，该表达式含义是获取AreaInformation API的结果集内的第1行、对应列名为area的字段值。此处配置为如果该值等于“area1”，就执行并行处理分支。
- 零售商信息RetailerInformation分支的条件类型配置为“不满足其他条件时”，表示如果不满足并行处理分支的条件，则执行零售商信息RetailerInformation分支。
图11 配置条件分支算子
在API目录找到供应商信息SupplierInformation API和销售评级SalesRating API并拖拽到画布，挂载到并行处理算子下。其中供应商信息SupplierInformation和销售评级SalesRating两个普通API的节点编码分别为NormalApi_3ad5c、NormalApi_01e7e。
单击画布上的并行处理算子打开配置面板，可以配置失败策略及分支超时时间（此处无需特殊配置，报错默认即可）。当并行处理分支被执行时，SupplierInformation和SalesRating两个分支会被同时调度。
图12 配置并行处理算子
拖拽“输出处理”算子到画布，挂载到3个普通API算子下。单击画布上的输出处理算子打开配置面板，添加结果集映射。
为能够输出3个普通API算子的结果，需要配置3条映射记录。节点映射表达式取普通API的结果，如“${NormalApi_3ad5c|payload}”、“${NormalApi_01e7e|payload}”、“${NormalApi_de62d|payload}”，结果集名称按照实际取值。
图13 配置输出处理算子
保存API工作量，然后调试并发布到集群。则后续调用者就可以通过调用API工作流中的入口API，实现根据客户所在地区的不同，返回不同的信息。