コンテンツにスキップ

スクリプト開発 / 公開関数 DFF.API

DFF.API(...) はデコレータを返し、修飾されたトップレベル関数を外部に公開し、Func API、定期実行タスク、MCP、関数ページ、またはデバッグ実行などを通じて呼び出せるようにします。

通常の Python インポート以外から呼び出す必要があるエントリポイント関数のみに @DFF.API(...) を使用すべきであり、プライベートな補助関数にこのデコレータを追加する必要はありません。

同じ Script 内では、デコレータで装飾された関数名は一意である必要があります。重複すると Script のロードに失敗します。

詳細なパラメータ一覧は以下のとおりです：

パラメータ 型 必須 / デフォルト値 説明
title str None 関数のエクスポート時の表示名。主に UI 表示に使用
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 関数が定期実行タスクによって実行される場合、指定した5段の 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 として公開されます。これらは説明用メタデータに過ぎず、ID や権限境界を確立するために使用することはできません。

例
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

一部の定期実行タスクに使用される関数について、関数の作成者が自動実行の頻度に要件を持っている場合があります。 この場合、このパラメータを指定することで、その関数に属する定期実行タスクを指定した 5 段の 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 拡張

4 つの標準 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 を返すと、ユーザー名が外部 ID として使用されます。文字列または数値を返すと、その値が外部 ID として使用されます。辞書を返す場合は、ID、表示名、メールアドレス情報も提供できます。

Danger

ログインに成功すると、現時点では管理者ロールを持つローカルユーザーが作成または更新されるため、この Func は管理者の信頼境界に属します。この 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

これらの 3 つのパラメータはカスタムメタデータを設定するために使用します。custom は JSON シリアライズ可能な値を受け入れ、custom_json は JSON テキストを受け入れ、custom_yaml は YAML テキストを受け入れます。一度に渡すことができるのは、これらのうち 1 つだけです。