Script Development / Exported Function DFF.API

DFF.API(...) returns a decorator, used to expose the decorated function and allow it to be invoked via API.

The detailed parameter list is as follows:

Parameter	Type	Required / Default	Description
title	str	Required	Display name of the exported function, primarily used for display purposes
catetory	str	"general"	Category the function belongs to, default is "general". Primarily used for classification/filtering in the function list
tags	list	None	List of tags for the function, primarily used for classification/filtering in the function list
tags[#]	str	Required	Function tag
timeout	int	30/3600	Timeout duration for the function. Unit: seconds, value 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 cron job, enforce a fixed crontab configuration. Minimum supported granularity is per minute
delayed_crontab	list	None	When the function is executed by a cron job, delay execution time after start. Multiple values indicate multiple executions with different delays
delayed_crontab[#]	int	Required	Delay execution time in seconds. Unit: seconds

Detailed explanations for each parameter are provided below:

Parameter title

Function titles support Chinese, making it convenient to display function names across DataFlux Func's various operation interfaces and documentation.

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

Parameter category / tags

Category and tag list the function belongs to. These parameters do not participate in or control the function's execution; they are primarily used to facilitate function management and classification. They can be used together or separately.

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

After specifying them, you can filter the function list using specific filtering parameters, such as:

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

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

Parameter timeout

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

Invocation Method	Default timeout
Sync API (Legacy: Auth Link)	35
Async API (Legacy: Batch)	3600
Cron Job (Legacy: Auto Trigger Config)	35

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

For executing functions within the DataFlux Func editor, the system ignores the timeout configuration and defaults to 60 seconds.

Danger

The maximum allowed value for timeout is 3600 seconds (i.e., 1 hour), aimed at protecting the system. Thoughtlessly setting all functions' timeout durations to the maximum may prevent timely detection of issues in code writing or design, potentially leading to queue blocking problems.

Therefore, the timeout parameter should be set based on actual requirements. A large number of long-running Sync API (Legacy: Auth Link) requests may block the task queue, and caching techniques should be considered when necessary.

Warning

An HTTP interface response taking more than 3 seconds is already considered very slow. Avoid configuring meaningless long timeout durations for functions.

Additionally, browsers themselves impose limitations on request durations (e.g., Chrome has a limit of 4 minutes). Thus, setting excessively long timeout values in Sync API (Legacy: Auth Link) calls is inherently ineffective.

Parameter cache_result

DataFlux Func provides built-in caching capabilities at the API level. When the same function and parameters are called exactly the same way, the system will directly return cached results.

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

Once a cache hit occurs, the API returns the result directly without actually executing the function.

Upon hitting the cache, the returned HTTP request headers will include the following indicator:

X-Dataflux-Func-Cache: Cached

Parameter fixed_crontab

For certain functions intended for use as cron jobs (Legacy: Auto Trigger Config), function writers might want to specify the frequency of automatic execution. In this case, this parameter can be specified to fix the associated cron job (Legacy: Auto Trigger Config) to the given Crontab expression.

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

Parameter delayed_crontab

For certain functions intended for use as cron jobs (Legacy: Auto Trigger Config), function writers might want to run the function at a more precise time (e.g., delay execution by 10 seconds after * * * * *). In this case, this parameter can be specified to define the delay in seconds before execution. Additionally, an array of delay times can be passed, allowing the function to execute multiple times at different delays.

This parameter guarantees only that execution starts after the specified delay, but does not guarantee execution precisely at the specified time.

This parameter is not suitable for cases involving long-running cron jobs (Legacy: Auto Trigger Config), 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 respectively, total of 2 executions
    '''
    pass