스크립트 개발 / 내보내기 함수 DFF.API

DFF.API(...) 는 데코레이터를 반환하며, 장식된 최상위 함수를 외부에 공개하여 Func API, 예약 작업, MCP, 함수 페이지 또는 디버그 실행 등을 통해 호출할 수 있도록 합니다.

일반 Python import 외부에서 호출해야 하는 진입 함수에만 @DFF.API(...)를 사용해야 하며, private 헬퍼 함수에는 이 데코레이터를 추가할 필요가 없습니다.

동일한 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	함수가 예약 작업에 의해 실행될 때 지정된 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의 다양한 운영 인터페이스 / 문서에서 표시하기 편리합니다.

@DFF.API('내 함수')
def my_func():
    pass

매개변수 require_api_auth

Func가 Func API를 통해 외부에 노출될 때, require_api_auth=True로 설정하여 호출자가 API Auth 인증을 수행하도록 요구할 수 있습니다.

@DFF.API('내 함수', require_api_auth=True)
def my_func():
    pass

Func API가 공개된 후 호출자는 함수의 입력 및 반환 구조에 의존하게 되므로, 이 둘을 안정적으로 유지해야 합니다.

매개변수 category / tags

함수가 속한 카테고리, 태그 목록은 자체적으로 함수의 실행에 참여하지도 제어하지도 않으며, 주로 함수를 쉽게 분류 관리하는 데 사용됩니다. 함께 사용하거나 각각 단독으로 사용할 수 있습니다.

실행 시, 카테고리와 태그는 각각 _DFF_FUNC_CATEGORY 및 _DFF_FUNC_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을 설정하는 것 자체도 의미가 없습니다.

매개변수 expires / queue

expires는 작업이 큐에서 대기할 수 있는 최대 시간을 제한하는 데 사용되며, 값 범위는 1 ~ 86400초입니다. 대기 시간이 초과되면 작업은 더 이상 실행을 시작하지 않습니다. 이는 실제 실행 시간을 제한하는 timeout과 다릅니다.

queue는 사용자 Worker 큐 번호를 지정하는 데 사용됩니다. 사용 가능한 번호는 현재 DataFlux Func의 Worker 구성에 따라 달라집니다.

매개변수 cache_result

DataFlux Func에는 API 수준의 캐시 처리가 내장되어 있습니다. 캐시 매개변수를 지정하면, 완전히 동일한 함수와 매개변수로 호출할 때 시스템이 캐시된 결과를 직접 반환합니다.

cache_result에는 양의 정수(초)만 사용해야 합니다. None 또는 0을 전달하면 캐시가 활성화되지 않습니다.

@DFF.API('내 함수', cache_result=30)
def my_func():
    pass

캐시가 적중되면 API가 결과를 직접 반환하며 함수는 실제로 실행되지 않습니다

캐시가 적중되면 반환되는 HTTP 요청 헤더에 다음 표시가 추가됩니다.

X-Dataflux-Func-Cache: Cached

매개변수 fixed_cron_expr

일부 예약 작업에 사용될 함수의 경우, 함수 작성자는 자동 실행 빈도에 대한 요구사항이 있을 수 있습니다. 이때 이 매개변수를 지정하여 이 함수에 속한 예약 작업을 지정된 5단 Cron 표현식으로 고정할 수 있습니다. 이 매개변수는 Script가 스케줄링 빈도를 반드시 제어해야 하는 경우에만 사용해야 하며, 그렇지 않으면 예약 작업 구성이 제어해야 합니다.

@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은 예약 작업에 지연이 구성되지 않은 경우에만 기본값으로 사용됩니다. 둘 다 단일 초(second) 값 또는 초 배열을 전달할 수 있으며, 배열을 전달하면 각 지정된 지연에 도달한 후 실행됩니다.

지연 실행은 함수가 지정된 시간보다 일찍 실행되지 않는다는 것만 보장하며, 지정된 시간에 도달한 후 함수가 즉시 실행된다는 것은 보장하지 않습니다

이 매개변수들은 지연 실행과 관련이 있는지 여부와 관계없이, 장시간 실행되는 예약 작업이 존재하는 경우에는 적용되지 않습니다

@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 메타데이터를 소비할 때 해석되며, 해석 결과가 유효하지 않으면 무시되고 데코레이터 선언은 변경되지 않습니다.

@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 설명의 다음 줄에 다음 기본 프롬프트가 바로 추가되며, 중간에 빈 줄이 없습니다:

**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에게 제공되는 지시사항일 뿐, 서버가 강제하는 확인 또는 인가 제어가 아닙니다.

@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는 인증만 담당해야 하며, 전달된 자격 증명을 기록, 영속화, 반환 또는 출력해서는 안 됩니다. 실패 정보에도 자격 증명 내용이 포함되어서는 안 되며, 인증에 필요한 최소한의 사용자 정보만 반환해야 합니다.

로그인 자격 증명은 동시에 Func 매개변수에 속하며, 설치 설정에 따라 작업 기록 또는 자체 모니터링 데이터에 보존될 수 있습니다. 로그인 통합을 활성화하기 전에 관련 설정을 먼저 확인해야 합니다.

매개변수 auto_run

auto_run은 자동 실행 진입점을 구성하는 데 사용되며, 동시에 integration='autoRun'을 설정합니다. 다음 표준 키 이름을 지원합니다:

키 이름	설명
cronExpr	Cron 표현식에 따라 트리거
onSystemLaunch	시스템 시작 시 트리거
onScriptPublish	Script 게시 후 트리거

이러한 트리거는 Func 매개변수를 제공하지 않으므로 자동 실행 진입점은 위치 매개변수나 키워드 매개변수를 요구할 수 없습니다. onScriptPublish는 게시된 Script 데이터 동기화가 완료된 후에만 시작되며 방금 게시된 코드를 실행합니다. 동기화에 실패하면 자동 실행을 건너뜁니다.

@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 텍스트를 받습니다. 한 번에 하나의 매개변수만 전달해야 합니다.