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

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

详细参数列表如下：

参数	类型	必须/默认值	说明
`title`	str	必须	函数导出的展示名，主要用于在展示
`catetory`	str	`"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 各种操作界面/文档中展示函数名称。

示例如下：

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

参数 category / tags

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

示例如下：

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

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

Text Only
# 根据 category 筛选
GET /api/v1/func-list?category=demo

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

参数 timeout

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

调用方式	`timeout`默认值
授权链接	默认值`35`
自动触发配置	默认值`35`
批处理	默认值`3600`

示例如下：

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

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

Danger

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

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

Warning

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

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

参数 cache_result

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

示例如下：

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

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

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

Text Only
X-Dataflux-Func-Cache: Cached

参数 fixed_crontab

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

示例如下：

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

参数 delayed_crontab

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

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

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

示例如下：

Python
@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