腳本開發 / 導出函數 DFF.API

DFF.API(...) 返回一個裝飾器，用於將被修飾的函數對外開放，允許使用 API 方式調用。

詳細參數列表如下：

參數	類型	必須 / 默認值	説明
title	str	必須	函數導出的展示名，主要用於在展示
catetory	str	"general"	函數所屬類別，默認為 "general"。主要用於函數列表的分類/篩選
tags	list	None	函數標籤列表，主要用於函數列表的分類/篩選
tags[#]	str	必須	函數標籤
timeout	int	30/3600	函數超時時間。 單位：秒，取值範圍 1 ~ 3600
cache_result	int	None	緩存結果數據時長。 單位：秒，None表示不緩存
fixed_crontab	str(Crontab-format)	None	當函數由定時任務執行時，強制固定的 Crontab 配置。 最小支持分鐘級
delayed_crontab	list	None	當函數由定時任務執行時，啓動後延遲執行時間，設置多個表示按照不同延遲多次執行
delayed_crontab[#]	int	必須	延遲執行秒數。 單位：秒

各參數的詳解見下文：

參數 title

函數標題方便在 DataFlux Func 各種操作界面 / 文檔中展示。

@DFF.API('我的函數')
def my_func():
    pass

參數 category / tags

函數所屬分類、標籤列表，本身並不參與也不控制函數的運行，主要用於方便分類管理函數。 分別使用或者各自單獨使用都可以。

@DFF.API('我的函數', category='demo', tags=['tag1', 'tag2']):
def my_func():
    pass

指定後，可通過指定篩選參數來過濾函數列表，如：

# 根據 category 篩選
GET /api/v1/func-list?category=demo

# 根據 tags 篩選（指定多個 tag 表示「同時包含」）
GET /api/v1/func-list?tags=tag1,tag2

參數 timeout

為了保護系統，所有在 DataFlux Func 中運行的函數都有運行時長限制，不允許無限制地運行下去。在未配置 timeout 時，不同的調用方式會有不同的默認值。

調用方式	timeout 默認值
同步執行的函數 API	35
異步執行的函數 API	3600
定時任務	35

@DFF.API('我的函數', timeout=30)
def my_func():
    pass

對於在 DataFlux Func 編輯器中執行函數，系統會忽略 timeout 配置，固定為 60 秒

Danger

timeout 允許配置的最大值為 3600 秒（即 1 小時），目的是保護系統。如果不經考慮直接將所有的函數的超時時間設置為最大，可能會無法及時瞭解代碼編寫、設計中存在的問題，同時導致隊列堵塞等問題。

因此 timeout 參數應當以實際需求為依據進行設置，大量長耗時函數 API 請求會導致任務隊列堵塞，必要時應使用緩存技術

Warning

一個 HTTP 接口響應時間超過 3 秒即可認為非常緩慢，應當注意不要為函數配置無意義的超長超時時間。

同時，瀏覽器本身也會對請求最長時間有限制（如：Chrome 為 4 分鐘），因此在函數 API 中設置過長的timeout本身也沒有意義

參數 cache_result

DataFlux Func 內置了 API 層面的緩存處理。 在指定的緩存參數後，當調用完全相同的函數和參數時，系統會直接返回緩存的結果。

@DFF.API('我的函數', cache_result=30):
def my_func():
    pass

命中緩存後，API 會直接返回結果，而函數並不會實際執行

命中緩存後，返回的 HTTP 請求頭會添加如下標示：

X-Dataflux-Func-Cache: Cached

參數 fixed_crontab

對於某些會用於定時任務的函數，函數編寫者可能會對自動運行的頻率有要求。 此時，可以指定本參數，將屬於本函數的定時任務固定為指定的 Crontab 表達式。

@DFF.API('我的函數', fixed_crontab='*/5 * * * *'):
def my_func():
    pass

參數 delayed_crontab

對於某些用於定時任務的函數，函數編寫者可能希望以更精確的時間運行（如在 * * * * * 的基礎上，延遲 10 秒運行）。 此時，可以指定本參數，在指定延遲的秒數。同時，也可以傳入秒數的數組，到達各個指定延遲時運行。

本參數只能保證在指定的時間後運行，並不能保證到達指定的時間後一定運行

本參數不適用於「存在長時間定時任務」的情況，無論這些長時間任務是否與延遲執行有關

@DFF.API('我的函數', delayed_crontab=10):
def my_func():
    '''
    延遲 10 秒執行
    '''
    pass

@DFF.API('我的函數 2', delayed_crontab=[0, 10]):
def my_func_2():
    '''
    延遲 0、10 秒執行，共執行 2 次
    '''
    pass