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". 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 tags
timeout	int	30/3600	Function timeout time. Unit: seconds, range 1 ~ 3600
cache_result	int	None	Cache result duration. 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 delay execution times after startup. Multiple values mean executing multiple times with different delays.
delayed_crontab[#]	int	Required	Delay execution time in seconds. Unit: seconds

Detailed explanations of each parameter are provided below:

Parameter title

The function title supports Chinese characters for easier display in various operation interfaces/documentation of DataFlux Func.

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

Parameter category / tags

The function's category and tag list do not participate in or control the function's execution but are mainly used for convenient classification and management. Both can be used individually or together.

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

After specifying, functions can be filtered using specific filtering parameters, such as:

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

# Filter by tags (specifying multiple tags means "all must include")
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	Default timeout Value
Synchronous API (Old Version: Authorized Link)	35
Asynchronous API (Old Version: Batch Processing)	3600
Scheduled Task (Old Version: Automatic Trigger Configuration)	35

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

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

Danger

The maximum allowable value for timeout is 3600 seconds (i.e., 1 hour), intended to protect the system. Setting all function timeouts 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: Authorized Link) may lead to task queue blockages; cache technology should be used when necessary.

Warning

An HTTP interface response time exceeding 3 seconds is considered very slow, so avoid configuring excessively long timeouts for functions.

Additionally, browsers themselves impose limits on request durations (e.g., Chrome is 4 minutes). Thus, setting overly long timeout values in synchronous APIs (Old Version: Authorized Link) is meaningless.

Parameter cache_result

DataFlux Func has built-in API-level caching handling. After specifying the cache parameter, when calling the exact same function and parameters, the system directly returns cached results.

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

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

After hitting the cache, the following identifier is added to the returned HTTP request headers:

X-Dataflux-Func-Cache: Cached

Parameter fixed_crontab

For some functions that will be used in scheduled tasks (Old Version: Automatic Trigger Configuration), the function author might have requirements for the frequency of automatic runs. In this case, you can specify this parameter to fix the scheduled tasks of the function (Old Version: Automatic Trigger Configuration) to the specified Crontab expression.

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

Parameter delayed_crontab

For some functions used in scheduled tasks (Old Version: Automatic Trigger Configuration), the function author may want more precise timing (e.g., delaying 10 seconds based on * * * * *). In this case, you can specify this parameter to define the delay in seconds. You can also pass an array of seconds, triggering at each specified delay.

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

This parameter is not applicable for cases where there are long-running scheduled tasks (Old Version: Automatic Trigger Configuration), regardless of whether these 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