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

DFF.API(...) 返回一个装饰器，用于将被修饰的函数对外开放，允许使用 API 方式调用。

详细参数列表如下：

参数	类型	必须 / 默认值	说明
title	str	必须	函数导出的展示名，主要用于在展示
catetory	str	"general"	函数所属类别，默认为 "general"。主要用于函数列表的分类/筛选
tags	list	None	函数标签列表，主要用于函数列表的分类/筛选
tags[#]	str	必须	函数标签
timeout	int	30/3600	函数超时时间。 单位：秒，取值范围 1 ~ 3600
cache_result	int	None	缓存结果数据时长。 单位：秒，None表示不缓存
fixed_crontab	str(Crontab-format)	None	当函数由定时任务执行时，强制固定的 Crontab 配置。 最小支持分钟级
delayed_crontab	list	None	当函数由定时任务执行时，启动后延迟执行时间，设置多个表示按照不同延迟多次执行
delayed_crontab[#]	int	必须	延迟执行秒数。 单位：秒

各参数的详解见下文：

参数 title

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

@DFF.API('我的函数')
def my_func():
    pass

参数 category / tags

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

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

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

# 根据 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

@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本身也没有意义

参数 cache_result

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

@DFF.API('我的函数', cache_result=30):
def my_func():
    pass

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

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

X-Dataflux-Func-Cache: Cached

参数 fixed_crontab

对于某些会用于定时任务的函数，函数编写者可能会对自动运行的频率有要求。 此时，可以指定本参数，将属于本函数的定时任务固定为指定的 Crontab 表达式。

@DFF.API('我的函数', fixed_crontab='*/5 * * * *'):
def my_func():
    pass

参数 delayed_crontab

对于某些用于定时任务的函数，函数编写者可能希望以更精确的时间运行（如在 * * * * * 的基础上，延迟 10 秒运行）。 此时，可以指定本参数，在指定延迟的秒数。同时，也可以传入秒数的数组，到达各个指定延迟时运行。

本参数只能保证在指定的时间后运行，并不能保证到达指定的时间后一定运行

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

@DFF.API('我的函数', delayed_crontab=10):
def my_func():
    '''
    延迟 10 秒执行
    '''
    pass

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