跳轉到

指令碼開發 / 匯出函式 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 文字。一次只應傳入其中一個引數。