指令碼開發 / 匯出函式 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