跳转至

脚本开发 / 导出函数 DFF.API

DFF.API(...) 返回一个装饰器，用于将被修饰的顶层函数对外开放，允许通过 Func API、定时任务、MCP、函数页面或调试执行等方式调用。

只有需要从普通 Python 导入之外调用的入口函数才应使用 @DFF.API(...)，私有辅助函数无需添加此装饰器。

同一个 Script 中，被装饰的函数名必须唯一，重名会导致 Script 加载失败。

详细参数列表如下：

参数 类型 必须 / 默认值 说明
title str None 函数导出的展示名，主要用于界面展示
require_api_auth bool False Func 通过 Func API 暴露时要求 API Auth
category str "general" 函数所属类别，默认为 "general"。主要用于函数列表的分类/筛选
tags list None 函数标签列表，主要用于函数列表的分类/筛选
　tags[#] str 必须 函数标签
timeout int / 动态引用 None 函数超时时间。
单位：秒，取值范围 1 ~ 3600
expires int / 动态引用 None 最大排队等待时长。
单位：秒，取值范围 1 ~ 86400
ignore_result bool None 是否忽略函数返回值；默认按执行功能决定，详见下文
cache_result int None 缓存结果数据时长。
单位：秒，使用正整数，None 或 0 表示不缓存
queue int / 动态引用 None 用户 Worker 队列编号
fixed_cron_expr str(Cron-format) None 当函数由定时任务执行时，强制使用指定的五段 Cron 表达式
fixed_delayed_cron_job int / list[int] None 强制定时任务使用指定的延迟执行秒数
delayed_cron_job int / list[int] / 动态引用 None 定时任务没有自行配置延迟时使用的默认延迟执行秒数
mcp_annotations dict None 标准 MCP 工具行为 Hint 及 confirmationHint 扩展
integration str None 内置集成，可选 "signIn" 或 "autoRun"
auto_run dict None 自动运行配置，同时设置 integration="autoRun"
is_hidden bool False 从普通 Func 发现结果中隐藏
custom JSON 可序列化值 None 自定义元数据
custom_json str(JSON) None 使用 JSON 文本编码的自定义元数据
custom_yaml str(YAML) None 使用 YAML 文本编码的自定义元数据

各参数的详解见下文：

参数 title

函数标题方便在 DataFlux Func 各种操作界面 / 文档中展示。

示例
1
2
3
@DFF.API('我的函数')
def my_func():
    pass

参数 require_api_auth

当 Func 通过 Func API 对外开放时，可以设置 require_api_auth=True，要求调用方通过 API Auth 鉴权。

示例
1
2
3
@DFF.API('我的函数', require_api_auth=True)
def my_func():
    pass

Func API 发布后，调用方会依赖函数的输入和返回结构，因此应保持二者稳定。

参数 category / tags

函数所属分类、标签列表，本身并不参与也不控制函数的运行，主要用于方便分类管理函数。 分别使用或者各自单独使用都可以。

运行时，分类和标签分别通过 _DFF_FUNC_CATEGORY 和 _DFF_FUNC_TAGS 暴露。它们仅属于描述性元数据，不能用于建立身份或权限边界。

示例
1
2
3
@DFF.API('我的函数', category='demo', tags=['tag1', 'tag2'])
def my_func():
    pass

指定后，可通过指定筛选参数来过滤函数列表，如：

HTTP 请求示例
1
2
3
4
5
# 根据 category 筛选
GET /api/v1/func-list?category=demo

# 根据 tags 筛选（指定多个 tag 表示「同时包含」）
GET /api/v1/func-list?tags=tag1,tag2

参数 timeout

为了保护系统，所有在 DataFlux Func 中运行的函数都有运行时长限制，不允许无限制地运行下去。在未配置 timeout 时，不同的调用方式会有不同的默认值。

调用方式 timeout 默认值
同步执行的函数 API 35
异步执行的函数 API 3600
定时任务 35
示例
1
2
3
@DFF.API('我的函数', timeout=30)
def my_func():
    pass

对于在 DataFlux Func 编辑器中执行函数，系统会忽略 timeout 配置，固定为 60 秒

Danger

timeout 允许配置的最大值为 3600 秒（即 1 小时），目的是保护系统。如果不经考虑直接将所有的函数的超时时间设置为最大，可能会无法及时了解代码编写、设计中存在的问题，同时导致队列堵塞等问题。

因此 timeout 参数应当以实际需求为依据进行设置，大量长耗时函数 API 请求会导致任务队列堵塞，必要时应使用缓存技术

Warning

一个 HTTP 接口响应时间超过 3 秒即可认为非常缓慢，应当注意不要为函数配置无意义的超长超时时间。

同时，浏览器本身也会对请求最长时间有限制（如：Chrome 为 4 分钟），因此在函数 API 中设置过长的timeout本身也没有意义

参数 expires / queue

expires 用于限制任务在队列中的最长等待时间，取值范围为 1 ~ 86400 秒。超过等待时间后，任务不会再开始执行；它与限制实际运行时长的 timeout 不同。

queue 用于指定用户 Worker 队列编号。可用编号取决于当前 DataFlux Func 的 Worker 配置。

参数 ignore_result

于 8.1.15 版本新增

ignore_result 控制函数执行结束后是否保留返回值：

值 行为
None 函数 API 默认保留返回值；定时任务（包括 auto_run.cronExpr 触发）默认忽略返回值
True 不保留返回值
False 保留返回值，供后续按 Task ID 查询；启用本地函数任务记录时，也会将返回值写入对应记录

同步函数 API 仍会直接返回函数返回值，异步函数 API 仍会返回 Task ID。设置 ignore_result=True 不会关闭任务记录，执行状态、异常和日志仍按既有配置记录。

需要保留定时任务的返回值时，可以显式设置 ignore_result=False：

保留定时任务返回值
1
2
3
@DFF.API('统计结果', ignore_result=False)
def collect_summary():
    return {'count': 10}

本地函数任务记录的配置方式见 部署和维护 / 系统指标和任务记录 / 任务记录。

按 Task ID 查询执行结果

于 8.1.15 版本新增

异步函数 API 响应中的 data.id 即为 Task ID。函数执行结束且结果被保留后，可使用以下接口查询：

HTTP
1
GET /api/v1/task-results/<Task ID>/do/get

查询成功时，data.status 表示执行状态，data.result 为函数返回值。函数正常返回 None 时，data.result 也会是 null，因此应结合 data.status 判断执行是否成功。

任务尚未完成、结果被忽略、结果已过期或 Task ID 不存在时，接口均返回未找到结果，不能据此区分任务正在执行或不存在。该接口不提供执行进度。

结果默认从函数执行结束起保留 1 天。可以在配置文件 config.yaml 中配置 _FUNC_TASK_RESULT_EXPIRES 调整保留秒数，默认值为 86400；本地函数任务记录仍按其自身的保留规则管理。

Warning

查询接口无需登录，持有 Task ID 即可读取对应结果。请将 Task ID 作为查询凭证妥善保管，避免向无权读取结果的人泄露。

参数 cache_result

DataFlux Func 内置了 API 层面的缓存处理。 在指定的缓存参数后，当调用完全相同的函数和参数时，系统会直接返回缓存的结果。

cache_result 只应使用正整数秒；传入 None 或 0 时不启用缓存。

示例
1
2
3
@DFF.API('我的函数', cache_result=30)
def my_func():
    pass

命中缓存后，API 会直接返回结果，而函数并不会实际执行

命中缓存后，返回的 HTTP 请求头会添加如下标识：

Text Only
1
X-Dataflux-Func-Cache: Cached

参数 fixed_cron_expr

对于某些会用于定时任务的函数，函数编写者可能会对自动运行的频率有要求。 此时，可以指定本参数，将属于本函数的定时任务固定为指定的五段 Cron 表达式。只有必须由 Script 控制调度频率时才应使用本参数，否则应由定时任务配置控制。

示例
1
2
3
@DFF.API('我的函数', fixed_cron_expr='*/5 * * * *')
def my_func():
    pass

参数 fixed_delayed_cron_job / delayed_cron_job

对于某些用于定时任务的函数，函数编写者可能希望以更精确的时间运行（如在 * * * * * 的基础上，延迟 10 秒运行）。 fixed_delayed_cron_job 会覆盖定时任务自身配置的延迟；delayed_cron_job 只在定时任务没有配置延迟时作为默认值。二者都可以传入单个秒数或秒数数组，传入数组时会在到达各个指定延迟后运行。

延迟执行只能保证函数不会早于指定时间运行，并不能保证函数在到达指定时间后立即运行

这些参数不适用于「存在长时间定时任务」的情况，无论这些长时间任务是否与延迟执行有关

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@DFF.API('我的函数', fixed_delayed_cron_job=10)
def my_func():
    '''
    延迟 10 秒执行
    '''
    pass

@DFF.API('我的函数 2', delayed_cron_job=[0, 10])
def my_func_2():
    '''
    延迟 0、10 秒执行，共执行 2 次
    '''
    pass

动态引用

delayed_cron_job、timeout、expires 和 queue 支持使用以下方法返回的动态引用：

  • DFF.ENV.ref(key, default=None)
  • DFF.STORE.ref(key, scope=None, default=None)
  • DFF.CACHE.ref(key, scope=None, default=None)

DFF.STORE.ref(...) 和 DFF.CACHE.ref(...) 省略 scope 时使用 REF。动态引用会在消费 Func 元数据时解析；解析结果无效时会被忽略，不会改变装饰器声明。

示例
1
2
3
4
5
6
7
@DFF.API(
    '环境控制的任务',
    timeout=DFF.ENV.ref('FUNC_TIMEOUT', default=35),
    queue=DFF.ENV.ref('FUNC_QUEUE', default=1),
)
def environment_controlled():
    return 'ok'

参数 mcp_annotations

当 Func 直接作为 MCP 工具暴露时，可以通过 mcp_annotations 声明工具行为。MCP2 list-func 和 MCP3 search-func 也会通过 annotations 元数据返回其中的标准 Hint。

Hint 类型 说明
readOnlyHint bool 工具不会修改环境
destructiveHint bool 会修改环境的工具可能产生破坏性变更
idempotentHint bool 使用相同参数重复调用不会产生额外影响
openWorldHint bool 工具可能与外部实体交互
confirmationHint bool / str 要求 Agent 在调用前取得用户确认的 DataFlux Func 扩展

四个标准 Hint 的值必须为布尔值。只有明确传入的标准 Hint 才会写入 annotations，空字典不会产生 annotations。

confirmationHint 不会写入标准 MCP annotations。传入 True 时，会在 Func 描述的下一行直接追加以下默认提示，中间不留空行：

Text Only
1
**The AI Agent MUST obtain the user's explicit confirmation before calling this tool. The AI Agent MUST NOT call this tool without that explicit confirmation.**

传入 False 时不追加内容；传入字符串时，会在下一行原样追加该字符串以替代默认提示。此项只是提供给 Agent 的指令，不是服务端强制执行的确认或授权控制。

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
@DFF.API(
    '读取本地用户',
    mcp_annotations={
        'readOnlyHint': True,
        'openWorldHint': False,
        'confirmationHint': True,
    },
)
def read_local_user(user_id):
    return {'user_id': user_id}

参数 integration / auto_run / is_hidden

integration 用于声明内置集成，可选值为 "signIn" 或 "autoRun"。只有明确需要对应集成行为时才应设置本参数。

integration="signIn"

"signIn" 是安装级登录入口。运行时会向 Func 传入 username 和 password；返回假值或空值会拒绝登录，返回 True 时使用用户名作为外部身份，返回字符串或数字时使用该值作为外部身份，返回字典时还可以提供身份、展示名和邮箱信息。

Danger

登录成功后，目前会创建或更新具有管理员角色的本地用户，因此该 Func 属于管理员信任边界。它应只负责认证，不得记录、持久化、返回或打印传入的凭据，失败信息也不得包含凭据内容，并且只应返回认证所需的最少用户信息。

登录凭据同时属于 Func 参数，并可能根据安装设置保留在任务记录或自监控数据中。启用登录集成前，应先检查相关设置。

参数 auto_run

auto_run 用于配置自动运行入口，同时会设置 integration="autoRun"。支持以下规范键名：

键名 说明
cronExpr 按 Cron 表达式触发
onSystemLaunch 系统启动时触发
onScriptPublish Script 发布后触发

这些触发不会提供 Func 参数，因此自动运行入口不能要求位置参数或关键字参数。onScriptPublish 只会在已发布 Script 数据同步完成后启动，并执行刚发布的代码；同步失败时会跳过自动运行。

示例
1
2
3
@DFF.API('自动运行入口', auto_run={'onSystemLaunch': True, 'onScriptPublish': True})
def auto_run_entry():
    return 'ok'

参数 is_hidden

设置 is_hidden=True 可以将 Func 从普通 Func 发现结果中隐藏。只有明确需要隐藏入口时才应使用本参数。

参数 custom / custom_json / custom_yaml

这三个参数用于设置自定义元数据：custom 接受可 JSON 序列化的值，custom_json 接受 JSON 文本，custom_yaml 接受 YAML 文本。一次只应传入其中一个参数。