Script Development / Export Function DFF.API

DFF.API(...) returns a decorator that exposes the decorated function to the outside, 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 of the exported function, mainly used for presentation
category	str	"general"	The category of the function, default is "general". Mainly used for classification/filtering in the function list
tags	list	None	The list of tags for the function, mainly used for classification/filtering in the function list
tags[#]	str	Required	The tag of the function
timeout	int	30/3600	The timeout duration of the function. Unit: seconds, range 1 ~ 3600
cache_result	int	None	The 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 Cron Job, enforce a fixed Crontab configuration. Minimum support is at the minute level
delayed_crontab	list	None	When the function is executed by a Cron Job, the delay time after startup, setting multiple values means executing multiple times with different delays
delayed_crontab[#]	int	Required	The delay duration in seconds. Unit: seconds

The detailed explanation of each parameter is as follows:

Parameter title

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

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

Parameter category / tags

The category and tag list of the function, which do not participate in or control the function's execution, are mainly used for convenient classification management of functions. They can be used separately or together.

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

After specifying, you can filter the function list 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
Sync API	35
Async API	3600
Cron Job	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 to 60 seconds

Danger

The maximum value allowed for timeout is 3600 seconds (i.e., 1 hour), to protect the system. If the timeout is set to the maximum for all functions without consideration, it may prevent timely identification of issues in code writing and design, and lead to queue congestion.

Therefore, the timeout parameter should be set based on actual needs. A large number of long-running Func API requests can cause task queue congestion. Caching techniques should be used when necessary.

Warning

An HTTP interface response time exceeding 3 seconds is considered very slow. It is important to avoid setting unnecessarily long timeout durations for functions.

Additionally, browsers themselves have limits on the maximum request duration (e.g., Chrome has a 4-minute limit). Therefore, setting excessively long timeout in Func APIs is meaningless.

Parameter cache_result

DataFlux Func has built-in API-level caching. When caching is specified, calling the exact same function and parameters will directly return the cached result.

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

When the cache is hit, the API will directly return the result, and the function will not actually execute

When the cache is hit, the following header will be added to the HTTP response:

X-Dataflux-Func-Cache: Cached

Parameter fixed_crontab

For some functions used in Cron Jobs, the function writer may have specific requirements for the automatic execution frequency. In this case, this parameter can be specified to fix the Cron Job of this function to the specified Crontab expression.

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

Parameter delayed_crontab

For some functions used in Cron Jobs, the function writer may want to run at more precise times (e.g., running 10 seconds after * * * * *). In this case, this parameter can be specified to run after the specified delay in seconds. Additionally, an array of seconds can be passed to run at each specified delay.

This parameter only ensures execution after the specified time, not that it will definitely run at the specified time

This parameter is not suitable for cases where there are long-running Cron Jobs, regardless of whether these long-running 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 at 0 and 10 seconds delay, totaling 2 executions
    '''
    pass