Tracecat项目中的表达式使用指南：数据引用与操作详解

Tracecat项目中的表达式使用指南：数据引用与操作详解

tracecat 😼 The open source alternative to Tines / Splunk SOAR. Build AI-assisted workflows, orchestrate alerts, and close cases fast. 项目地址: https://gitcode.com/gh_mirrors/tr/tracecat

引言

在自动化工作流系统中，数据在不同操作步骤间的传递和转换是核心功能之一。Tracecat作为一款强大的自动化工作流工具，提供了完善的表达式系统，让用户能够灵活地引用和操作各种数据源。本文将深入解析Tracecat中的表达式系统，帮助开发者高效构建复杂的工作流。

表达式基础概念

Tracecat的表达式系统采用${{ <context>.<expression> }}语法结构，支持多种上下文环境：

1. 动作输出引用：通过ACTIONS上下文获取工作流中前序动作的执行结果
2. 触发器数据引用：通过TRIGGER上下文访问触发工作流的原始数据
3. 密钥管理：通过SECRETS上下文安全地使用敏感信息
4. 函数调用：通过FN上下文执行内置函数进行数据转换

各上下文详解

ACTIONS上下文：动作间数据传递

ACTIONS上下文允许引用同一工作流中其他动作的输出结果。其语法为：

${{ ACTIONS.<action_slug>.result.<jsonpath> }}

技术要点：

• 动作名称会被转换为小写字母和下划线组合的形式（slugified）
• 使用JSONPath语法访问嵌套数据结构
• 数据在动作开始执行时被解析

实际应用示例： 假设有一个获取天气数据的动作"Get weather"，我们可以这样引用其输出：

value:
  temperature: ${{ ACTIONS.get_weather.result.data.current.temperature_2m }}
  precipitation: ${{ ACTIONS.get_weather.result.data.current.precipitation_probability }}

TRIGGER上下文：访问触发数据

当工作流通过Webhook或手动触发时，TRIGGER上下文提供了访问原始触发数据的途径。

Webhook场景示例：

url: https://api.example.com/endpoint
params:
  user_id: ${{ TRIGGER.data.user.id }}
  event_type: ${{ TRIGGER.data.event }}

安全提示：

• 始终验证来自外部的触发数据
• 考虑使用JSON Schema验证数据结构

SECRETS上下文：安全管理敏感信息

Tracecat内置的密钥管理系统允许安全地存储和使用敏感数据。

使用方式：

${{ SECRETS.<name>.<key> }}

安全特性：

• 工作区级别的访问控制
• 静态加密存储
• 运行时内存中解密，执行后立即清除

FN上下文：内置函数库

Tracecat提供了丰富的内置函数，涵盖数据处理、日期操作、文本处理等多个领域。

常用函数类别：

1. JSON处理：

   • deserialize_json：JSON字符串转对象
   • serialize_json：对象转JSON字符串
   • prettify_json：格式化JSON

2. 日期时间处理：

   • to_datetime：字符串转日期对象
   • format_datetime：日期格式化
   • hours_between：计算时间差

3. 文本处理：

   • regex_extract：正则表达式提取
   • uppercase：转大写

4. IP地址处理：

   • check_ip_version：检查IP版本
   • ipv4_is_public：判断是否为公网IP

函数调用示例：

result: ${{ FN.to_datetime(ACTIONS.get_log.result.timestamp) }}

高级特性

类型转换

Tracecat支持灵活的类型转换，语法有两种形式：

1. 内联形式：${{ int(<expression>) }}
2. 后缀形式：${{ <expression> -> int }}

支持的类型转换：

• int：转换为整数
• float：转换为浮点数
• str：转换为字符串
• bool：转换为布尔值（支持多种真值表示）

运算符支持

Tracecat表达式支持标准运算符：

• 算术运算：+, -, *, /
• 字符串连接：+
• 列表/字典操作

运算示例：

${{ (ACTIONS.get_count.result + 1) * 2 }}

最佳实践

1. 数据验证：在使用前验证引用的数据是否存在
2. 错误处理：考虑使用FN.lookup安全访问可能不存在的属性
3. 性能优化：避免在循环中执行复杂表达式
4. 可读性：对于复杂表达式，使用YAML的多行语法提高可读性

总结

Tracecat的表达式系统提供了强大而灵活的数据操作能力，是构建复杂自动化工作流的基础。通过合理运用各种上下文和函数，开发者可以实现高效的数据处理和流转，满足各种业务场景的需求。掌握这些表达式技巧将显著提升工作流开发的效率和质量。

tracecat 😼 The open source alternative to Tines / Splunk SOAR. Build AI-assisted workflows, orchestrate alerts, and close cases fast. 项目地址: https://gitcode.com/gh_mirrors/tr/tracecat