服务API调用组件

服务API调用组件（ServiceCall）用于在流程中发起内网业务服务的 HTTP 调用。

概念说明

本文档是 平台接口 概念的具体配置说明。建议先阅读平台接口概念，了解整体架构。

概述

服务API调用组件用于调用内网微服务，将上游流程的数据传递给目标服务。请求方法、请求头与认证为内置能力，无需手动配置，只需选择服务名称、填写 API 地址并选择请求体的行为模式。

配置项

配置项	说明
服务名称	要调用的微服务名称，必填
API地址	要请求的业务服务 API 地址，例如：api/Test/SendMessage
请求体行为模式	指定请求 Body 值的来源，必填，缺省为「前端请求穿透」
输出到最终结果	开启后该组件结果作为接口返回值

服务名称取值

界面名称	值（ServiceName）	说明
Chameleon（内部调用）	Chameleon	系统内置功能，一般业务方不需要关心该值
系统级微服务	SystemSlave	系统级微服务，常用于单租户安装版或多租户共享微服务场景。需要在主站配置文件中配置该服务节点信息，SecurityKey 需要和主站的配置一致，请求微服务时使用同主站同样的 token

请求体行为模式取值

请求体行为模式用于指定请求 Body 的值来源：

界面名称	值（Behavior）	说明
前端请求穿透	0	直接把前端请求体透传给目标服务，缺省值
传递上游组件结果	4	请求体为上游组件的执行结果
传递上游组件结果+上下文字典	1	请求体为上游组件执行结果与上下文字典的组合
传递上下游交互协议	5	请求体为上下游之间的交互协议
传递上下游交互协议+上下文字典	2	请求体为上下游交互协议与上下文字典的组合
传递上游最终结果	6	请求体为上游的最终结果
传递上游最终结果+上下文字典	3	请求体为上游最终结果与上下文字典的组合

内置功能

tip

• 请求方法仅支持 POST
• 请求头和认证为内置功能，无需手动配置
• 只需配置服务名称和 API 路由地址即可完成调用

使用场景

• 内网微服务调用
• 业务系统集成
• 数据同步处理

下一步

• MOU数据权限 - 数据权限控制

属性明细

以下内容面向技术实现与 AI 检索，说明服务API调用组件的节点元数据。

节点元数据

服务API调用组件由 FlowCmpType.ServiceCall 标识：

属性名	类型	含义	取值/存储值
type	string	组件类型	固定为 "ServiceCall"
ServiceName	string	微服务名称	"Chameleon" / "SystemSlave"
API	string	请求的 API 地址	例："api/Test/SendMessage"
Behavior	string	请求体行为模式	"0"~"6"，缺省 "0"
IsFinalResult	string(bool)	是否输出到最终结果	"true" / "false"
order	string	同级排序	例："3"

元数据存储示例

{
  "ID": "svc1",
  "type": "ServiceCall",
  "ServiceName": "SystemSlave",
  "API": "api/Test/SendMessage",
  "Behavior": "0",
  "IsFinalResult": "true",
  "order": "3"
}

服务端执行逻辑

服务API调用组件由 ServiceCallComponentManager（继承 InterfaceComponentManagerBase）实现，组件类型为 FlowComponentTypeEnum.ServiceCall。

节点 meta 中的所有值均以字符串存储，服务端统一通过 SafeGet("Key") 读取字符串。

执行时机与场景

流程执行到该节点时，向目标微服务发起一次 HTTP POST 调用，并把响应写回上下文。分为系统内置调用与外部服务调用两类。

输入参数（meta 键）

键	读取方式	含义
ServiceName	meta.SafeGet("ServiceName")	服务名称；Chameleon 走内置调用，SystemSlave 走系统级微服务
API	meta.SafeGet("API")	API 地址；内置调用时为内置函数名（如 file_download）
Behavior	meta.SafeGet("Behavior")	请求体来源，"0"~"6"
IsFinalResult	meta.SafeGet("IsFinalResult")	"true" 时结果写入 context.Result
IsDisabled	meta.SafeGet("IsDisabled") == "true"	为 true 时跳过本组件

执行步骤

1. 校验 ServiceName、API 非空。
2. 若 ServiceName == "Chameleon"：调用内置函数 InternalCall(context, api)：
   • file_download：从 ChameleonContext.Current.GetBody() 反序列化 CommonRequestModel，取首个 fileid，经 IChameleonFileService.DownloadAsync 下载；写 context.DicParam["DownloadFileName"] = file.FileName，返回 file.DownloadStream；
   • 其它 API：抛「不支持的内置 API」异常。 随后 context.CmpResult = result。
3. 否则（外部服务）：
   • ServiceName == "SystemSlave"：host = ChameleonAppSettingConfigHelper.Get().SystemSlaveHost，token = ChameleonContext.Current.GetToken()；
   • 其它服务：host = ServiceName；host 为空抛「服务未注册」；
   • 拼接 host（补 /）+ API，并把前端 QueryString 追加上去；
   • 构造 HttpRequestMessage（POST），Accept: application/json，AppendChameleonHeaders(token)；存在 HttpContext 时追加 IP 头；
   • 按 Behavior 生成请求体（见下表）；
   • 通过 IHttpClientFactory.CreateClient(ServiceName) 发送请求；
   • 响应非成功或非 200：若状态码为 510 / 401 且响应体可反序列化为 ResponseResult，抛出携带 Code / moreMessage / action / duration / popType / placement / redirectUrl 的异常；否则抛出带 uri 与状态码的异常；
   • 成功：读取响应体字符串，result = JsonDocument.Parse(responseBody)，context.CmpResult = responseBody。
4. IsFinalResult = "true" 时 context.Result = result。
5. 调用 ExecuteNextAsync 继续下游。

请求体行为模式

Behavior	请求体内容
0（缺省）	前端请求体 ChameleonContext.Current.GetBody()
1	{ DicParam, Result = CmpResult }
2	{ DicParam, Result = TransferResult }
3	{ DicParam, Result }
4	CmpResult
5	TransferResult
6	Result

序列化使用 Newtonsoft.Json，忽略循环引用与 null 值。字典与交互协议字段的含义见 组件上下文。

输出与上下文

场景	context.CmpResult	context.Result（IsFinalResult = true）
外部服务	响应体字符串	JsonDocument
内置 file_download	文件流 Stream	文件流 Stream

内置下载还会写入 context.DicParam["DownloadFileName"]。

权限、安全与限制

• 请求头与鉴权由 AppendChameleonHeaders(token) 内置处理；SystemSlave 使用当前用户 token，且 SecurityKey 需与主站配置一致。
• 请求方法固定为 POST；前端 Query 参数会自动透传。
• IP 头为可选：调度任务等无 HttpContext 的场景会跳过。
• 组件未显式设置请求超时，使用 HttpClientFactory 的默认配置。

异常与校验

• 校验期：ServiceName 为空抛「服务名称必填」，API 为空抛「API 地址必填」。
• 执行期：服务未注册、请求失败、内置下载缺少 fileid、不支持的内置 API 均抛出异常。