跳轉至

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

DFF.API(...) 返回一個裝飾器，用於將被修飾的頂層函數對外開放，允許通過 Func API、定時任務、MCP、函數頁面或調試執行等方式調用。

只有需要從普通 Python 導入之外調用的入口函數才應使用 @DFF.API(...)，私有輔助函數無需添加此裝飾器。

同一個 Script 中，被裝飾的函數名必須唯一，重名會導致 Script 加載失敗。

詳細參數列表如下：

參數 類型 必須 / 默認值 説明
title str None 函數導出的展示名，主要用於界面展示
require_api_auth bool False Func 通過 Func API 暴露時要求 API Auth
category str "general" 函數所屬類別，默認為 "general"。主要用於函數列表的分類/篩選
tags list None 函數標籤列表，主要用於函數列表的分類/篩選
　tags[#] str 必須 函數標籤
timeout int / 動態引用 None 函數超時時間。
單位：秒，取值範圍 1 ~ 3600
expires int / 動態引用 None 最大排隊等待時長。
單位：秒，取值範圍 1 ~ 86400
cache_result int None 緩存結果數據時長。
單位：秒，使用正整數，None 或 0 表示不緩存
queue int / 動態引用 None 用户 Worker 隊列編號
fixed_cron_expr str(Cron-format) None 當函數由定時任務執行時，強制使用指定的五段 Cron 表達式
fixed_delayed_cron_job int / list[int] None 強制定時任務使用指定的延遲執行秒數
delayed_cron_job int / list[int] / 動態引用 None 定時任務沒有自行配置延遲時使用的默認延遲執行秒數
mcp_annotations dict None 標準 MCP 工具行為 Hint 及 confirmationHint 擴展
integration str None 內置集成，可選 signIn 或 autoRun
auto_run dict None 自動運行配置，同時設置 integration='autoRun'
is_hidden bool False 從普通 Func 發現結果中隱藏
custom JSON 可序列化值 None 自定義元數據
custom_json str(JSON) None 使用 JSON 文本編碼的自定義元數據
custom_yaml str(YAML) None 使用 YAML 文本編碼的自定義元數據

各參數的詳解見下文：

參數 title

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

示例
1
2
3
@DFF.API('我的函數')
def my_func():
    pass

參數 require_api_auth

當 Func 通過 Func API 對外開放時，可以設置 require_api_auth=True，要求調用方通過 API Auth 鑑權。

示例
1
2
3
@DFF.API('我的函數', require_api_auth=True)
def my_func():
    pass

Func API 發佈後，調用方會依賴函數的輸入和返回結構，因此應保持二者穩定。

參數 category / tags

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

運行時，分類和標籤分別通過 _DFF_FUNC_CATEGORY 和 _DFF_FUNC_TAGS 暴露。它們僅屬於描述性元數據，不能用於建立身份或權限邊界。

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

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

HTTP 請求示例
1
2
3
4
5
# 根據 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
示例
1
2
3
@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本身也沒有意義

參數 expires / queue

expires 用於限制任務在隊列中的最長等待時間，取值範圍為 1 ~ 86400 秒。超過等待時間後，任務不會再開始執行；它與限制實際運行時長的 timeout 不同。

queue 用於指定用户 Worker 隊列編號。可用編號取決於當前 DataFlux Func 的 Worker 配置。

參數 cache_result

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

cache_result 只應使用正整數秒；傳入 None 或 0 時不啓用緩存。

示例
1
2
3
@DFF.API('我的函數', cache_result=30)
def my_func():
    pass

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

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

Text Only
1
X-Dataflux-Func-Cache: Cached

參數 fixed_cron_expr

對於某些會用於定時任務的函數，函數編寫者可能會對自動運行的頻率有要求。 此時，可以指定本參數，將屬於本函數的定時任務固定為指定的五段 Cron 表達式。只有必須由 Script 控制調度頻率時才應使用本參數，否則應由定時任務配置控制。

示例
1
2
3
@DFF.API('我的函數', fixed_cron_expr='*/5 * * * *')
def my_func():
    pass

參數 fixed_delayed_cron_job / delayed_cron_job

對於某些用於定時任務的函數，函數編寫者可能希望以更精確的時間運行（如在 * * * * * 的基礎上，延遲 10 秒運行）。 fixed_delayed_cron_job 會覆蓋定時任務自身配置的延遲；delayed_cron_job 只在定時任務沒有配置延遲時作為默認值。二者都可以傳入單個秒數或秒數數組，傳入數組時會在到達各個指定延遲後運行。

延遲執行只能保證函數不會早於指定時間運行，並不能保證函數在到達指定時間後立即運行

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

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@DFF.API('我的函數', fixed_delayed_cron_job=10)
def my_func():
    '''
    延遲 10 秒執行
    '''
    pass

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

動態引用

delayed_cron_job、timeout、expires 和 queue 支持使用以下方法返回的動態引用：

  • DFF.ENV.ref(key, default=None)
  • DFF.STORE.ref(key, scope=None, default=None)
  • DFF.CACHE.ref(key, scope=None, default=None)

DFF.STORE.ref(...) 和 DFF.CACHE.ref(...) 省略 scope 時使用 REF。動態引用會在消費 Func 元數據時解析；解析結果無效時會被忽略，不會改變裝飾器聲明。

示例
1
2
3
4
5
6
7
@DFF.API(
    '環境控制的任務',
    timeout=DFF.ENV.ref('FUNC_TIMEOUT', default=35),
    queue=DFF.ENV.ref('FUNC_QUEUE', default=1),
)
def environment_controlled():
    return 'ok'

參數 mcp_annotations

當 Func 直接作為 MCP 工具暴露時，可以通過 mcp_annotations 聲明工具行為。MCP2 list-func 和 MCP3 search-func 也會通過 annotations 元數據返回其中的標準 Hint。

Hint 類型 説明
readOnlyHint bool 工具不會修改環境
destructiveHint bool 會修改環境的工具可能產生破壞性變更
idempotentHint bool 使用相同參數重複調用不會產生額外影響
openWorldHint bool 工具可能與外部實體交互
confirmationHint bool / str 要求 Agent 在調用前取得用户確認的 DataFlux Func 擴展

四個標準 Hint 的值必須為布爾值。只有明確傳入的標準 Hint 才會寫入 annotations，空字典不會產生 annotations。

confirmationHint 不會寫入標準 MCP annotations。傳入 True 時，會在 Func 描述的下一行直接追加以下默認提示，中間不留空行：

Text Only
1
**The AI Agent MUST obtain the user's explicit confirmation before calling this tool. The AI Agent MUST NOT call this tool without that explicit confirmation.**

傳入 False 時不追加內容；傳入字符串時，會在下一行原樣追加該字符串以替代默認提示。此項只是提供給 Agent 的指令，不是服務端強制執行的確認或授權控制。

示例
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
@DFF.API(
    '讀取本地用户',
    mcp_annotations={
        'readOnlyHint': True,
        'openWorldHint': False,
        'confirmationHint': True,
    },
)
def read_local_user(user_id):
    return {'user_id': user_id}

參數 integration / auto_run / is_hidden

integration 用於聲明內置集成，可選值為 signIn 或 autoRun。只有明確需要對應集成行為時才應設置本參數。

integration='signIn'

signIn 是安裝級登錄入口。運行時會向 Func 傳入 username 和 password；返回假值或空值會拒絕登錄，返回 True 時使用用户名作為外部身份，返回字符串或數字時使用該值作為外部身份，返回字典時還可以提供身份、展示名和郵箱信息。

Danger

登錄成功後，目前會創建或更新具有管理員角色的本地用户，因此該 Func 屬於管理員信任邊界。它應只負責認證，不得記錄、持久化、返回或打印傳入的憑據，失敗信息也不得包含憑據內容，並且只應返回認證所需的最少用户信息。

登錄憑據同時屬於 Func 參數，並可能根據安裝設置保留在任務記錄或自監控數據中。啓用登錄集成前，應先檢查相關設置。

參數 auto_run

auto_run 用於配置自動運行入口，同時會設置 integration='autoRun'。支持以下規範鍵名：

鍵名 説明
cronExpr 按 Cron 表達式觸發
onSystemLaunch 系統啓動時觸發
onScriptPublish Script 發佈後觸發

這些觸發不會提供 Func 參數，因此自動運行入口不能要求位置參數或關鍵字參數。onScriptPublish 只會在已發佈 Script 數據同步完成後啓動，並執行剛發佈的代碼；同步失敗時會跳過自動運行。

示例
1
2
3
@DFF.API('自動運行入口', auto_run={'onSystemLaunch': True, 'onScriptPublish': True})
def auto_run_entry():
    return 'ok'

參數 is_hidden

設置 is_hidden=True 可以將 Func 從普通 Func 發現結果中隱藏。只有明確需要隱藏入口時才應使用本參數。

參數 custom / custom_json / custom_yaml

這三個參數用於設置自定義元數據：custom 接受可 JSON 序列化的值，custom_json 接受 JSON 文本，custom_yaml 接受 YAML 文本。一次只應傳入其中一個參數。