Script Development / Export Function DFF.API

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

The detailed parameter list is as follows:

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

Detailed explanations of each parameter are provided below:

Parameter title

The function title supports Chinese characters, making it convenient for displaying the function name in various operation interfaces/documentation of DataFlux Func.

@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 execution but are mainly used for easier classification and management of functions. Both can be used separately or together.

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

After specifying these, you can filter the function list by providing specific filtering parameters, such as:

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

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

Parameter timeout

To protect the system, all functions running in DataFlux Func have runtime limits and cannot run indefinitely. If timeout is not configured, different calling methods will have different default values.

Calling Method	timeout Default Value
Synchronous API (Old version: Auth Link)	35
Asynchronous API (Old version: Batch Processing)	3600
Scheduled Task (Old version: Auto Trigger Config)	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 sets it to a fixed 60 seconds.

Danger

The maximum allowable value for timeout is 3600 seconds (i.e., 1 hour), intended to protect the system. Setting the timeout for all functions to the maximum without consideration may prevent timely awareness of issues in code writing and design, while also causing queue blockages.

Therefore, the timeout parameter should be set based on actual needs. A large number of long-running synchronous API requests (old version: auth link) can cause task queue blockages; caching techniques should be considered when necessary.

Warning

An HTTP interface response time exceeding 3 seconds can be considered very slow. Be cautious about setting excessively long timeouts for functions unnecessarily.

Additionally, browsers themselves impose limits on request durations (e.g., Chrome has a limit of 4 minutes). Thus, setting an overly long timeout in synchronous APIs (old version: auth link) is meaningless.

Parameter cache_result

DataFlux Func includes built-in API-level caching handling. After specifying the cache parameter, when calling the same function and parameters, the system will directly return the cached result.

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

If the cache is hit, the API will directly return the result without actually executing the function.

When the cache is hit, the following identifier will be added to the returned HTTP request headers:

X-Dataflux-Func-Cache: Cached

Parameter fixed_crontab

For some functions that will be used for scheduled tasks (old version: auto trigger config), the function writer may have requirements regarding the frequency of automatic runs. In this case, this parameter can be specified to fix the scheduled task (old version: auto trigger config) for this function to a designated Crontab expression.

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

Parameter delayed_crontab

For some functions used for scheduled tasks (old version: auto trigger config), the function writer may want to run them at more precise times (such as delaying execution by 10 seconds based on * * * * *). In this case, this parameter can be specified, providing the delay in seconds. It is also possible to pass an array of seconds, triggering runs at each specified delay.

This parameter only guarantees execution after the specified time and does not ensure immediate execution at the exact specified time.

This parameter is not suitable for cases involving long-duration scheduled tasks (old version: auto trigger config), regardless of whether these long-duration tasks are related to delayed execution.

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

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