Script Development / Export Function DFF.API

DFF.API(...) returns a decorator used to expose the decorated function, allowing it to be called via API.

The detailed parameter list is as follows:

Parameter	Type	Required / Default	Description
title	str	Required	The display name for the exported function, mainly used for interface presentation.
category	str	"general"	The category to which the function belongs, default is "general". Mainly used for categorizing/filtering the function list.
tags	list	None	The list of function tags, mainly used for categorizing/filtering the function list.
tags[#]	str	Required	A function tag.
timeout	int	30/3600	Function timeout duration. Unit: seconds, valid range 1 ~ 3600.
cache_result	int	None	Duration to cache the result data. Unit: seconds, None means no caching.
fixed_crontab	str(Crontab-format)	None	When the function is executed by a scheduled task, enforce a fixed Crontab configuration. Minimum support is minute-level.
delayed_crontab	list	None	When the function is executed by a scheduled task, the delay time after startup. Setting multiple values means multiple executions with different delays.
delayed_crontab[#]	int	Required	Delay execution seconds. Unit: seconds.

Detailed explanations for each parameter are provided below:

Parameter title

The function title is convenient for display in various DataFlux Func operation interfaces / documentation.

@DFF.API('My Function')
def my_func():
    pass

Parameters category / tags

The function's category and tag list do not participate in or control the function's operation themselves. They are mainly used to facilitate the categorized management of functions. They can be used together or separately.

@DFF.API('My Function', category='demo', tags=['tag1', 'tag2'])
def my_func():
    pass

After specification, the function list can be filtered by specifying filter parameters, such as:

# Filter by category
GET /api/v1/func-list?category=demo

# Filter by tags (specifying multiple tags means "contains all")
GET /api/v1/func-list?tags=tag1,tag2

Parameter timeout

To protect the system, all functions running in DataFlux Func have a runtime limit and are not allowed to run indefinitely. When timeout is not configured, different invocation methods have different default values.

Invocation Method	timeout Default Value
Synchronously executed function API	35
Asynchronously executed function API	3600
Scheduled Task	35

@DFF.API('My Function', timeout=30)
def my_func():
    pass

For functions executed in the DataFlux Func editor, the system ignores the timeout configuration and fixes it at 60 seconds.

Danger

The maximum allowed value for timeout is 3600 seconds (i.e., 1 hour), to protect the system. Setting the timeout for all functions to the maximum without consideration may prevent timely identification of issues in code writing/design and cause queue blockage problems.

Therefore, the timeout parameter should be set based on actual requirements. A large number of long-running function API requests can lead to task queue blockage. Caching techniques should be used when necessary.

Warning

An HTTP interface response time exceeding 3 seconds can be considered very slow. Care should be taken not to configure unnecessarily long timeout durations for functions.

Additionally, browsers themselves impose limits on maximum request times (e.g., Chrome is 4 minutes). Therefore, setting excessively long timeout values in function APIs is also meaningless.

Parameter cache_result

DataFlux Func has built-in caching at the API level. After specifying the caching parameter, when calling the exact same function with the same parameters, the system will directly return the cached result.

@DFF.API('My Function', cache_result=30)
def my_func():
    pass

When the cache is hit, the API returns the result directly, and the function does not actually execute.

After a cache hit, the returned HTTP request header will include the following identifier:

X-Dataflux-Func-Cache: Cached

Parameter fixed_crontab

For certain functions that may be used in scheduled tasks, the function author may have requirements for the automatic execution frequency. In this case, this parameter can be specified to fix the scheduled task belonging to this function to the specified Crontab expression.

@DFF.API('My Function', fixed_crontab='*/5 * * * *')
def my_func():
    pass

Parameter delayed_crontab

For certain functions used in scheduled tasks, the function author may wish to run at more precise times (e.g., based on * * * * *, but delayed by 10 seconds). In this case, this parameter can be specified to set the delay in seconds. An array of seconds can also be passed to run at each specified delay.

This parameter only guarantees execution after the specified time, not at the specified time.

This parameter is not suitable for situations where 'long-running scheduled tasks exist', regardless of whether those long tasks are related to delayed execution.

@DFF.API('My Function', delayed_crontab=10)
def my_func():
    '''
    Execute after a 10-second delay.
    '''
    pass

@DFF.API('My Function 2', delayed_crontab=[0, 10])
def my_func_2():
    '''
    Execute after 0 and 10 seconds delay, for a total of 2 executions.
    '''
    pass