Skip to content

스크립트 개발 / 기본 개념

DataFlux Func에는 DataFlux Func에만 있는 몇 가지 고유한 개념이 있습니다. 이 문서에서는 이에 대해 설명합니다.

1. 스크립트 세트, 스크립트 및 함수

스크립트 세트, 스크립트 및 함수는 '개발 / 스크립트 라이브러리'에서 생성할 수 있으며, DataFlux Func의 핵심 개념입니다. ID는 사용자가 생성/코드 작성 시 직접 지정합니다.

  • '스크립트 세트'는 여러 스크립트의 집합이며, ID는 생성 시 사용자가 직접 지정하고, 스크립트만 포함할 수 있습니다.
  • '스크립트'는 Python 스크립트 자체이며, 반드시 특정 스크립트 세트에 속합니다. ID는 생성 시 사용자가 직접 지정합니다.
  • '함수'는 DataFlux Func에서 @DFF.API(...) 데코레이터로 장식된 최상위 함수를 가리키며, 함수 API, 예약 작업 등에서 호출의 진입 함수로 사용될 수 있습니다.

스크립트 세트는 폴더가 아닙니다

스크립트 세트는 폴더와 유사하지만, 이 '폴더'는 일반적인 Python 코딩에서의 폴더와 관련이 없습니다.

DataFlux Func에서 코딩할 때는 스크립트 세트, 스크립트 및 함수의 ID가 다수 사용되며, 이러한 ID 사이에는 긴밀한 관계가 있습니다.

스크립트 세트, 스크립트 및 함수 ID 간의 관계

스크립트 세트, 스크립트 및 함수의 계층 관계에 따라 하위 개념의 ID는 반드시 상위 개념의 ID를 포함합니다.

ID가 demo인 스크립트 세트가 존재한다고 가정하면, 이 스크립트 세트에 속하는 모든 스크립트는 반드시 demo__(이중 밑줄)로 시작합니다.

또한 이 스크립트 세트에 ID가 demo__test인 스크립트가 있고, 이 스크립트에 def hello(...) 함수가 포함되어 있다면, 이 함수의 ID는 demo__test.hello가 됩니다.

ID 예시 표는 다음과 같습니다.

개념 ID 예시
스크립트 세트 demo
스크립트 demo__test
함수 demo__test.hello

코딩에서 상호 참조

DataFlux Func의 스크립트에서는 다른 스크립트를 참조하여 코드를 재사용할 수 있습니다.

스크립트 demo__script_a가 존재하고 이 스크립트에 함수 func_a()가 포함되어 있다고 가정합니다. 그러면 스크립트 demo__script_b에서 이 함수를 참조할 때 다음과 같은 방법을 사용할 수 있습니다.

demo__script_a
1
2
def func_a():
    pass
demo__script_b
1
2
3
4
import demo__script_b

def test():
    return demo__script_b.func_a()

Python의 as 문도 마찬가지로 사용할 수 있습니다.

demo__script_b
1
2
3
4
import demo__script_b as b

def test():
    return b.func_a()

필요한 함수만 가져오기 위해 from ... import 문을 사용할 수도 있습니다.

demo__script_b
1
2
3
4
from demo__script_b import func_a

def test():
    return func_a()

같은 스크립트 세트에 속하는 스크립트 간의 참조는 스크립트 세트 ID를 생략하고, __(이중 밑줄)로 시작하는 축약 형식으로 나타낼 수 있습니다:

demo__script_b
1
2
3
4
from __script_b import func_a

def test():
    return func_a()

가능하면 축약 형식 사용

스크립트 세트 내부에서 상호 참조할 때는 가능하면 축약 형식(즉, 스크립트 세트 ID를 생략하고 __로 시작하는 형식)을 사용해야 합니다.

이렇게 하면 전체 스크립트 세트를 복제하여 스크립트 세트 ID가 변경된 후에도, 복제된 새 스크립트 세트 내의 코드는 여전히 이 스크립트 세트 내의 스크립트를 올바르게 참조할 수 있습니다.

2. 커넥터

커넥터는 '개발 / 커넥터'에서 생성할 수 있으며, DataFlux Func가 제공하는 외부 시스템 연결 도구입니다. ID는 생성 시 사용자가 직접 지정합니다.

실제로 DataFlux Func에서 Python 코드를 작성하는 것은 원래 Python과 크게 다르지 않습니다. 개발자는 커넥터를 완전히 무시하고 코드에서 직접 외부 시스템에 연결할 수 있습니다.

하지만 연결 풀(Connection Pool) 개념이 있는 일부 외부 시스템의 경우, 커넥터에는 연결 풀이 내장되어 있어 함수가 반복 실행되는 동안 연결을 유지하고 외부 시스템과의 연결을 반복적으로 생성 / 종료하지 않아도 됩니다.

사용자가 ID가 mysql인 커넥터를 이미 구성했다고 가정하면, 이 커넥터의 작업 객체를 가져오는 코드는 다음과 같습니다.

Python
1
mysql = DFF.CONN('mysql')

구체적으로 서로 다른 커넥터는 각각 다른 작업 방법과 매개변수를 가집니다. 자세한 내용은 스크립트 개발 / 커넥터 객체 DFF.CONN을 참조하세요.

3. 환경 변수

환경 변수는 '개발 / 환경 변수'에서 생성할 수 있으며, DataFlux Func가 제공하는 간단한 Key-Value 구성 읽기 도구입니다. ID는 생성 시 사용자가 직접 지정합니다.

환경 변수는 동일한 코드가 다른 환경에서 실행되는 시나리오에 특히 적합합니다.

스크립트가 액세스해야 하는 시스템이 테스트 / 프로덕션 환경을 구분하는 경우, 환경 변수를 설정하면 코드를 변경하지 않고도 테스트 / 프로덕션 환경을 전환할 수 있습니다.

사용자가 ID가 api_endpoint인 환경 변수를 이미 구성했다고 가정하면, 이 환경 변수의 값을 가져오는 코드는 다음과 같습니다.

Python
1
api_endpoint = DFF.ENV('api_endpoint')

4. 함수 API

함수 API는 '관리 / 함수 API'에서 생성할 수 있으며, 외부에서 DataFlux Func의 함수를 호출하는 일반적인 방법입니다. 호출 과정은 동기 또는 비동기를 선택할 수 있고, 동기 실행 시 함수 실행이 완료된 후 결과를 호출자에게 직접 반환할 수 있습니다.

함수에 함수 API를 생성하면 여러 가지 다양한 호출 방법을 지원합니다.

함수 API는 GET, POST 두 가지 방식을 지원합니다. 두 방식의 매개변수 전달은 모두 '간소화 형식'과 '표준 형식'을 지원합니다.

또한 POST 방식의 '간소화' 형식은 파일 업로드도 지원합니다. 다음은 다양한 호출 방식의 기능 지원 목록입니다.

호출 방식 kwargs 매개변수 전달 kwargs 매개변수 유형 options 전달 파일 업로드 임의 형식의 Body 제출
GET 간소화 형식 지원 문자열만 가능 미지원 미지원 미지원
GET 표준 형식 지원 JSON의 데이터 유형 지원 미지원 미지원
POST 간소화 형식 지원 문자열만 가능 미지원 지원 지원
POST 표준 형식 지원 JSON의 데이터 유형 지원 미지원 미지원

전달 방식이 다르면 매개변수 유형에 제한이 있을 수 있습니다.

kwargs의 매개변수에 문자열만 전달할 수 있는 호출 방식의 경우, 함수에서 매개변수에 대한 형변환을 수행해야 합니다. 함수 API 목록에서 'API 호출 예시'를 클릭하면 구체적인 호출 방식을 확인할 수 있습니다.

다음과 같은 함수가 있다고 가정합니다.

Python
1
2
3
@DFF.API('내 함수')
def my_func(x, y):
    pass

이 함수를 위해 생성된 '함수 API' ID가 func-api-xxxxx이고, 전달된 매개변수는 x=100(정수), y="hello"(문자열)이라고 가정합니다.

그러면 다양한 호출 방식은 다음과 같습니다.

GET 간소화 형식으로 매개변수 전달

함수의 매개변수가 비교적 간단하다면 GET 간소화 형식으로 매개변수를 전달할 수 있으며, 인터페이스가 더 직관적입니다.

URL에 매개변수를 전달할 때는 문자열 "100"과 정수 100을 구분할 수 없으므로, 함수가 호출될 때 수신되는 매개변수는 모두 문자열입니다. 함수는 직접 매개변수에 대한 형변환을 수행해야 합니다.

Text Only
1
GET /api/v1/al/func-api-xxxxx/s?x=100&y=hello

가독성을 위해 예시는 URLEncode 이전의 내용이며, 실제 URL 매개변수는 URLEncode가 필요합니다.

GET 표준 형식으로 매개변수 전달

어떤 경우에는 POST 요청을 보낼 수 없을 때 GET 방식으로 인터페이스를 호출할 수도 있습니다.

GET 표준 형식으로 매개변수를 전달할 때는 전체 kwargs를 JSON 직렬화한 후 URL 매개변수로 전달하면 됩니다. 매개변수가 실제로는 여전히 JSON 형식으로 전송되므로 매개변수의 원래 유형이 모두 유지됩니다. 함수는 더 이상 매개변수에 대한 형변환을 수행할 필요가 없습니다.

이 예시에서 함수가 수신하는 x 매개변수는 정수이므로 형변환이 필요 없습니다.

Text Only
1
GET /api/v1/al/func-api-xxxxx?kwargs={"x":100,"y":"hello"}

가독성을 위해 예시는 URLEncode 이전의 내용이며, 실제 URL 매개변수는 URLEncode가 필요합니다.

POST 간소화 형식으로 매개변수 전달

어떤 경우에는 요청 본문이 JSON인 HTTP 요청을 보낼 수 없을 때, Form 형식과 유사하게 매개변수를 전달할 수 있으며, 각 필드명이 매개변수명이 됩니다.

Form 형식으로 데이터를 제출할 때는 문자열 "100"과 정수 100을 구분할 수 없으므로, 함수가 호출될 때 수신되는 매개변수는 모두 문자열이며, 함수는 직접 매개변수에 대한 형변환을 수행해야 합니다.

Text Only
1
2
3
4
POST /api/v1/al/func-api-xxxxx/s
Content-Type: x-www-form-urlencoded

x=100&y=hello

또한 POST 간소화 형식으로 매개변수를 전달할 때는 파일 업로드도 추가로 지원하며(매개변수/필드 이름은 반드시 files여야 합니다), form-data/multipart 방식으로 처리해야 합니다.

페이지의 HTML 코드 예시는 다음과 같습니다.

HTML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<html>
    <body>
        <h1>파일 업로드</h1>
        <input id="file" type="file" name="files" required />
        <input id="submit" type="submit" value="업로드"/>
    </body>
    <script>
        // 함수 API 주소 (이 페이지와 DataFlux Func가 다른 도메인에 있는 경우 http://domain:port/api/v1/al/func-api-xxxxx/s 전체를 작성해야 함)
        // 참고: 파일 업로드는 반드시 간소화 형식 함수 API를 사용해야 함
        var API_URL = '/api/v1/al/func-api-xxxxx/s';

        document.querySelector('#submit').addEventListener('click', function(event) {
            // 업로드 버튼 클릭 후 FormData 객체를 생성하여 요청 본문으로 전송
            var data = new FormData();
            data.append('x', '100');
            data.append('y', 'hello');
            data.append('files', document.querySelector('#file').files[0]);

            var xhr = new XMLHttpRequest();
            xhr.open('POST', API_URL);
            xhr.send(data);
        });
    </script>
</html>

POST 표준 형식으로 매개변수 전달

POST 표준 형식으로 매개변수를 전달하는 것은 가장 일반적인 호출 방식입니다. 매개변수가 JSON 형식으로 요청 본문을 통해 전송되므로 매개변수의 원래 유형이 모두 유지됩니다. 함수는 더 이상 매개변수에 대한 형변환을 수행할 필요가 없습니다.

이 예시에서 함수가 수신하는 x 매개변수는 정수이므로 형변환이 필요 없습니다.

Text Only
1
2
3
4
5
6
7
8
9
POST /api/v1/al/func-api-xxxxx
Content-Type: application/json

{
  "kwargs": {
    "x": 100,
    "y": "hello"
  }
}

5. 예약 작업

예약 작업은 '관리 / 예약 작업'에서 생성할 수 있으며, DataFlux Func가 정기적으로 함수를 자동 호출하도록 하는 데 사용됩니다.

함수에 예약 작업을 생성하면 함수는 지정된 Crontab 표현식에 따라 정기적으로 실행되며, 외부에서 호출할 필요가 없습니다.

그렇기 때문에 실행되는 함수의 모든 매개변수가 이미 충족되어 있어야 합니다. 즉:

  1. 함수에 입력 매개변수가 필요하지 않습니다.
  2. 함수에 입력 매개변수가 필요하지만 모두 선택 매개변수입니다.
  3. 함수에 필수 매개변수가 필요하고, 예약 작업에서 해당 매개변수에 구체적인 값을 구성합니다.

함수 런타임에 속한 실행 기능 구분

함수에 '예약 작업'과 다른 실행 기능이 동시에 구성되어 있고, 서로 다른 실행 기능에서 구분하여 처리하려면 내장 변수 _DFF_CRONTAB을 확인하여 구분할 수 있습니다:

Python
1
2
3
4
5
6
7
8
9
@DFF.API('내 함수')
def my_func(x, y):
    result = x + y

    if _DFF_CRON_EXPR:
        # 예약 작업에서만 로그 출력
        print(f'x + y = {result}')

    return