스크립트 개발 / API 인증

"함수 API"로 생성된 HTTP API에 인터페이스 인증을 추가할 수 있습니다.

현재 지원되는 인터페이스 인증은 다음과 같습니다.

인증 유형	설명
고정 필드	요청의 Header, Query 또는 Body에 특정 값을 가진 필드가 포함되어야 하는지 검증합니다
HTTP Basic	표준 HTTP Basic 인증 (브라우저에서 접속 시 로그인 창 표시)
HTTP Digest	표준 HTTP Digest 인증 (브라우저에서 접속 시 로그인 창 표시)
인증 함수	직접 작성한 함수를 인증 함수로 지정

사용자는 "관리 / API 인증"에서 인증 구성을 추가한 후, "함수 API 구성"에서 추가된 인증 구성을 지정할 수 있습니다.

보안 요구사항이 높은 경우 반드시 HTTPS 방식으로 인터페이스에 접근하십시오

1. 고정 필드 인증

고정 필드 인증은 가장 간단한 인증 방식으로, 클라이언트와 DataFlux Func가 요청의 특정 위치(Header, Query 또는 Body)에 특정 필드와 필드 값을 포함하기로 약속하고, 매 호출 시 이 내용을 첨부하여 인증을 완료합니다.

매 요청마다 요청 헤더에 x-auth-token="my-auth-token"을 포함해야 한다고 약속했다면, 다음과 같이 호출하여 인증을 완료할 수 있습니다.

Text Only
GET /api/v1/al/func-api-xxxxx
x-auth-token: my-auth-token

고정 필드 인증을 여러 개 구성한 경우, 하나만 일치하면 인증 통과로 간주됩니다

Query 및 Body에서 인증에 사용되는 필드는 인증 통과 후 시스템이 자동으로 삭제하며, 함수로 전달되지 않습니다

2. HTTP Basic / HTTP Digest

브라우저에서 직접 지원하는 인증 방식입니다.

이 방식으로 인증되는 인터페이스를 브라우저 주소창에서 직접 접속하면, 브라우저는 사용자 이름/비밀번호 입력 창을 표시합니다.

프로그래밍 방식으로 접근해야 하는 경우, 다음 코드를 참고하십시오.

Python
import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# HTTP Basic 인증
resp = requests.get(url_1, auth=HTTPBasicAuth('user', 'password'))

# HTTP Digest 인증
resp = requests.get(url_2, auth=HTTPDigestAuth('user', 'password'))

3. 인증 함수

인터페이스 인증 방식이 복잡하거나 특수한 경우(예: 비즈니스 시스템 연동이 필요한 경우 등) 직접 함수를 작성하여 인증하는 방식을 선택할 수 있습니다.

인증에 사용되는 함수는 매개변수가 필요하지 않으며, True를 반환하면 인증 성공, 다른 값을 반환하거나 오류를 발생시키면 실패를 의미합니다.

인증 함수에서는 내장 변수 _DFF_HTTP_REQUEST를 사용하여 요청 관련 정보를 얻을 수 있습니다: 스크립트 개발 / 내장 변수 / _DFF_HTTP_REQUEST

예시
@DFF.API('인증 함수')
def my_auth_func():
    return _DFF_HTTP_REQUEST['headers']['x-auth-token'] == 'my-auth-token'

주의할 점은 인증 실패 시 반환 내용에 따라 인터페이스의 응답 형식도 달라진다는 것입니다.

False 반환문자열 반환JSON 반환오류 발생

예시
@DFF.API('인증 함수')
def my_auth_func():
    return False

인증 실패 시 False를 직접 반환하면, 인터페이스 응답 본문에는 구체적인 오류 정보가 포함되지 않습니다:

인터페이스 응답 본문
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : false,
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

예시
@DFF.API('인증 함수')
def my_auth_func():
    return 'Bad User!'

인증 실패 시 문자열을 반환하면, 이 문자열이 detail 필드로 반환됩니다:

인터페이스 응답 본문
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : "Bad User!",
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

예시
@DFF.API('인증 함수')
def my_auth_func():
    return { 'error': 'Bad User!' }

인증 실패 시 JSON을 반환하면, 이 JSON이 detail 필드로 반환됩니다:

인터페이스 응답 본문
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "error": "Bad User!"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

예시
@DFF.API('인증 함수')
def my_auth_func():
    raise Exception('Bad User!')

인증 함수에서 오류가 발생하면, Func 프레임워크 차원에서는 이 Exception이 비즈니스 로직 때문인지 코드 자체의 오류 때문인지 인식할 수 없으므로, 일반적인 오류 정보를 detail 필드로 반환합니다:

인터페이스 응답 본문
{
  "ok": false,
  "error": 401.99,
  "reason": "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "name"               : "Func.Runner",
    "id"                 : "task-RWLH3EuCRfYl",
    "triggerTime"        : 1755170213.119,
    "startTime"          : 1755170213.122,
    "endTime"            : 1755170213.13,
    "status"             : "failure",
    "exceptionType"      : "UserScriptException",
    "exception"          : "In User Script: Exception('Bad User!')",
    "exceptionFrom"      : "userScript",
    "originExceptionType": "Exception",
    "originException"    : "Exception('Bad User!')"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}